Changeset 042f345


Ignore:
Timestamp:
01/22/10 17:03:08 (11 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:
fc710bf
Parents:
f68d5b8
Message:

Some updates to the Doxygen documentation in libtrace.h - not complete, just what I've done so far.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • lib/libtrace.h.in

    rb7a328d r042f345  
    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
    68 *          Perry Lorier
    … …  
    4244 *
    4345 * This library provides a per packet interface into a trace file, or a live
    44  * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
    45  * pcap etc.
     46 * captures.  It supports ERF, DAG cards, PCAP, Linux and BSD native sockets,
     47 * legacy ERF formats etc.
    4648 *
    4749 * @par Usage
    48  * See the example/ directory in the source distribution for some simple examples
     50 * See the example/ directory in the source distribution for some simple
     51 * examples
     52 *
    4953 * @par Linking
    5054 * To use this library you need to link against libtrace by passing -ltrace
    … …  
    138142            ((@LIBTRACE_MAJOR@<<16)|(@LIBTRACE_MID@<<8)|(@LIBTRACE_MINOR@))
    139143
     144/** Replaced with the current SVN revision number when 'make dist' is invoked
     145 *  to create a distributable tarball */
    140146#define LIBTRACE_SVN_REVISION 0
     147
     148/** DAG driver version installed on the current system */
    141149#define DAG_DRIVER_V "@DAG_VERSION_NUM@"
    142150   
    … …  
    171179typedef struct libtrace_filter_t libtrace_filter_t;
    172180
    173 /** If a packet has memory allocated
    174  * If the packet has allocated it's own memory it's buffer_control should
    175  * be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be
    176  * free()'d.  If it's doing zerocopy out of memory owned by something else
    177  * it should be TRACE_CTRL_EXTERNAL.
    178  * @note the letters p and e are magic numbers used to detect if the packet
    179  * wasn't created properly
     181/** If the packet has allocated its own memory the buffer_control should be
     182 * set to TRACE_CTRL_PACKET, so that the memory will be freed when the packet
     183 * is destroyed. If the packet has been zerocopied out of memory owned by
     184 * something else, e.g. a DAG card, it should be TRACE_CTRL_EXTERNAL.
     185 *
     186 * @note The letters p and e are magic numbers used to detect if the packet
     187 * wasn't created properly.
    180188 */
    181189typedef enum {
    182         TRACE_CTRL_PACKET='p',
    183         TRACE_CTRL_EXTERNAL='e'
     190        TRACE_CTRL_PACKET='p',  /**< Buffer memory is owned by the packet */
     191        TRACE_CTRL_EXTERNAL='e' /**< Buffer memory is owned by an external source */
    184192} buf_control_t;
     193
    185194/** The size of a packet's buffer when managed by libtrace */
    186195#define LIBTRACE_PACKET_BUFSIZE 65536
    187196
    188 /** libtrace error information */
     197/** Libtrace error information */
    189198typedef struct trace_err_t{
    190199        int err_num;            /**< error code */
    … …  
    214223};
    215224
    216 /** Enumeration of DLT supported by libtrace
     225/** Enumeration of DLTs supported by libtrace
    217226 */
    218227typedef enum {
    … …  
    221230        TRACE_DLT_PPP = 9,
    222231        TRACE_DLT_ATM_RFC1483 = 11,
     232       
    223233        /* Sigh. This is handled in files with LINKTYPE's */
    224234#ifdef __OpenBSD__
    … …  
    239249typedef enum {
    240250    /* TRACE_TYPE_LEGACY = 0            Obsolete */
    241        TRACE_TYPE_HDLC_POS = 1,
     251       TRACE_TYPE_HDLC_POS = 1,         /**< HDLC over POS */
    242252       TRACE_TYPE_ETH = 2,              /**< 802.3 style Ethernet */
    243253       TRACE_TYPE_ATM = 3,              /**< ATM frame */
    … …  
    245255       TRACE_TYPE_NONE = 5,             /**< Raw IP frames */
    246256       TRACE_TYPE_LINUX_SLL = 6,        /**< Linux "null" framing */
    247        TRACE_TYPE_PFLOG = 7,            /**< FreeBSD's PFlug */
     257       TRACE_TYPE_PFLOG = 7,            /**< FreeBSD's PFlog */
    248258    /* TRACE_TYPE_LEGACY_DEFAULT        Obsolete */
    249        TRACE_TYPE_POS = 9,
     259       TRACE_TYPE_POS = 9,              /**< Packet-over-SONET */
    250260    /* TRACE_TYPE_LEGACY_ATM            Obsolete */
    251261    /* TRACE_TYPE_LEGACY_ETH            Obsolete */
    252        TRACE_TYPE_80211_PRISM = 12,
    253        TRACE_TYPE_AAL5 = 13,
     262       TRACE_TYPE_80211_PRISM = 12,     /**< 802.11 Prism frames */
     263       TRACE_TYPE_AAL5 = 13,            /**< ATM Adaptation Layer 5 frames */
    254264       TRACE_TYPE_DUCK = 14,         /**< Pseudo link layer for DUCK packets */
    255265       TRACE_TYPE_80211_RADIO = 15,  /**< Radiotap + 802.11 */
    … …  
    260270} libtrace_linktype_t;
    261271
    262 /** RT protocol base format identifiers
    263  * This is used to say what kind of packet is being sent over the rt protocol
     272/** RT protocol base format identifiers.
     273 * This is used to describe the capture format of the packet is being sent
     274 * using the RT protocol.
    264275 */
    265276enum base_format_t {
    266         TRACE_FORMAT_ERF          =1,
    267         TRACE_FORMAT_PCAP         =2,
    268         TRACE_FORMAT_PCAPFILE     =3,
    269         TRACE_FORMAT_WAG          =4,
    270         TRACE_FORMAT_RT           =5,
    271         TRACE_FORMAT_LEGACY_ATM   =6,
    272         TRACE_FORMAT_LEGACY_POS   =7,
    273         TRACE_FORMAT_LEGACY_ETH   =8,
    274         TRACE_FORMAT_LINUX_NATIVE =9,
    275         TRACE_FORMAT_DUCK         =10,
    276         TRACE_FORMAT_BPF          =11,
    277         TRACE_FORMAT_TSH          =12,
    278         TRACE_FORMAT_ATMHDR       =13,
    279         TRACE_FORMAT_LEGACY_NZIX  =14
     277        TRACE_FORMAT_ERF          =1,   /**< ERF (DAG capture format) */
     278        TRACE_FORMAT_PCAP         =2,   /**< Live PCAP capture */
     279        TRACE_FORMAT_PCAPFILE     =3,   /**< PCAP trace file */
     280        TRACE_FORMAT_WAG          =4,   /**< WAG live capture (Obsolete) */
     281        TRACE_FORMAT_RT           =5,   /**< RT network protocol */
     282        TRACE_FORMAT_LEGACY_ATM   =6,   /**< Legacy ERF for ATM capture */
     283        TRACE_FORMAT_LEGACY_POS   =7,   /**< Legacy ERF for POS capture */
     284        TRACE_FORMAT_LEGACY_ETH   =8,   /**< Legacy ERF for ETH capture */
     285        TRACE_FORMAT_LINUX_NATIVE =9,   /**< Linux native interface capture */
     286        TRACE_FORMAT_DUCK         =10,  /**< DAG Clock information */
     287        TRACE_FORMAT_BPF          =11,  /**< BSD native interface capture */
     288        TRACE_FORMAT_TSH          =12,  /**< TSH trace format */
     289        TRACE_FORMAT_ATMHDR       =13,  /**< Legacy ATM header capture */
     290        TRACE_FORMAT_LEGACY_NZIX  =14   /**< Legacy format used for NZIX traces */
    280291};
    281292
    … …  
    303314        TRACE_RT_METADATA       =18,/**< Packet contains server meta-data */
    304315
    305         TRACE_RT_DATA_SIMPLE    = 1000, /**< Trace types that know their link
    306                                           * type
    307                                           */
     316        /** Not actually used - all DATA types begin from this value */
     317        TRACE_RT_DATA_SIMPLE    = 1000,
     318       
     319        /** RT is encapsulating an ERF capture record */
    308320        TRACE_RT_DATA_ERF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_ERF,
     321        /** RT is encapsulating a WAG capture record */
    309322        TRACE_RT_DATA_WAG       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_WAG,
     323        /** RT is encapsulating a Legacy ATM capture record */
    310324        TRACE_RT_DATA_LEGACY_ATM=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ATM,
     325        /** RT is encapsulating a Legacy POS capture record */
    311326        TRACE_RT_DATA_LEGACY_POS=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_POS,
     327        /** RT is encapsulating a Legacy ETH capture record */
    312328        TRACE_RT_DATA_LEGACY_ETH=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ETH,
     329        /** RT is encapsulating a Linux native capture record */
    313330        TRACE_RT_DATA_LINUX_NATIVE=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_NATIVE,
     331        /** RT is encapsulating a BSD native capture record */
    314332        TRACE_RT_DATA_BPF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_BPF,
     333        /** RT is encapsulating a TSH capture record */
    315334        TRACE_RT_DATA_TSH       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_TSH,
    316 
     335        /** RT is encapsulating an ATM header capture record */
    317336        TRACE_RT_DATA_ATMHDR = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ATMHDR,
     337        /** RT is encapsulating a Legacy NZIX capture record */
    318338        TRACE_RT_DATA_LEGACY_NZIX=TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_LEGACY_NZIX,
    319         TRACE_RT_DATA_DLT               = 2000, /**< Pcap doesn't store the
    320                                                   * linktype per packet, and
    321                                                   * thus we have to store it
    322                                                   * in here.  sigh.
    323                                                   */
     339
     340        /** As PCAP does not store the linktype with the packet, we need to
     341         * create a separate RT type for each supported DLT, starting from
     342         * this value */
     343        TRACE_RT_DATA_DLT               = 2000,
     344        /** RT is encapsulating a PCAP capture record with a NULL linktype */
    324345        TRACE_RT_DLT_NULL               =TRACE_RT_DATA_DLT+TRACE_DLT_NULL,
     346        /** RT is encapsulating a PCAP capture record with an Ethernet
     347         * linktype */
    325348        TRACE_RT_DLT_EN10MB             =TRACE_RT_DATA_DLT+TRACE_DLT_EN10MB,
     349        /** RT is encapsulating a PCAP capture record with an 802.11
     350         * linktype */
    326351        TRACE_RT_DLT_IEEE802_11         =TRACE_RT_DATA_DLT+TRACE_DLT_IEEE802_11,
     352        /** RT is encapsulating a PCAP capture record with a Linux SLL
     353         * linktype */
    327354        TRACE_RT_DLT_LINUX_SLL          =TRACE_RT_DATA_DLT+TRACE_DLT_LINUX_SLL,
     355        /** RT is encapsulating a PCAP capture record with a PFlog linktype */
    328356        TRACE_RT_DLT_PFLOG              =TRACE_RT_DATA_DLT+TRACE_DLT_PFLOG,
     357        /** RT is encapsulating a PCAP capture record with an AAL5 linktype */
    329358        TRACE_RT_DLT_ATM_RFC1483        =TRACE_RT_DATA_DLT+TRACE_DLT_ATM_RFC1483,
     359        /** Unused value marking the end of the valid range for PCAP RT
     360         * encapsulation */
    330361        TRACE_RT_DATA_DLT_END           = 2999,
     362        /** Unused value marking the end of the valid range for all RT packet
     363         * types */
    331364        TRACE_RT_LAST                   = (2<<31)
    332365} libtrace_rt_types_t;
    … …  
    338371        TRACE_IPPROTO_IGMP      = 2,    /**< Internet Group Management Protocol */
    339372        TRACE_IPPROTO_IPIP      = 4,    /**< IP encapsulated in IP */
    340         TRACE_IPPROTO_TCP       = 6,    /**< Transmission Controll Protocol */
     373        TRACE_IPPROTO_TCP       = 6,    /**< Transmission Control Protocol */
    341374        TRACE_IPPROTO_UDP       = 17,   /**< User Datagram Protocol */
    342375        TRACE_IPPROTO_IPV6      = 41,   /**< IPv6 over IPv4 */
    343         TRACE_IPPROTO_ROUTING   = 43,   /**< IPv6 routing header */
     376        TRACE_IPPROTO_ROUTING   = 43,   /**< IPv6 Routing header */
    344377        TRACE_IPPROTO_FRAGMENT  = 44,   /**< IPv6 Fragmentation header */
    345378        TRACE_IPPROTO_RSVP      = 46,   /**< Resource Reservation Protocol */
    346379        TRACE_IPPROTO_GRE       = 47,   /**< General Routing Encapsulation */
    347380        TRACE_IPPROTO_ESP       = 50,   /**< Encapsulated Security Payload [RFC2406] */
    348         TRACE_IPPROTO_AH        = 51,   /**< Autehtnication Header [RFC2402 */
     381        TRACE_IPPROTO_AH        = 51,   /**< Authentication Header [RFC2402] */
    349382        TRACE_IPPROTO_ICMPV6    = 58,   /**< ICMPv6 */
    350383        TRACE_IPPROTO_NONE      = 59,   /**< IPv6 no next header */
    … …  
    354387} libtrace_ipproto_t;
    355388
    356 /** Ethertypes */
     389/** Ethertypes supported by Libtrace */
    357390typedef enum {
    358391        /* Numbers <=1500 are of course, LLC/SNAP */
    … …  
    368401} libtrace_ethertype_t;
    369402
    370 /** The libtrace packet structure, applications shouldn't be
     403/** The libtrace packet structure. Applications shouldn't be
    371404 * meddling around in here
    372405 */
    373406typedef struct libtrace_packet_t {
    374         struct libtrace_t *trace;       /**< pointer to the trace */
    375         void *header;                   /**< pointer to the framing header */
    376         void *payload;                  /**< pointer to the link layer */
    377         void *buffer;                   /**< allocated buffer */
    378         libtrace_rt_types_t  type;      /**< rt protocol type for the packet */
    379         buf_control_t buf_control;      /**< who owns the memory */
     407        struct libtrace_t *trace;       /**< Pointer to the trace */
     408        void *header;                   /**< Pointer to the framing header */
     409        void *payload;                  /**< Pointer to the link layer */
     410        void *buffer;                   /**< Allocated buffer */
     411        libtrace_rt_types_t  type;      /**< RT protocol type for the packet */
     412        buf_control_t buf_control;      /**< Describes memory ownership */
    380413        int capture_length;             /**< Cached capture length */
    381414        void *l3_header;                /**< Cached l3 header */
    … …  
    384417
    385418
    386 /** Trace directions
    387  * Note that these are the directions used by convention, more directions
     419/** Trace directions.
     420 * Note that these are the directions used by convention. More directions
    388421 * are possible, not just these 3, and that they may not conform to this
    389422 * convention.
    … …  
    420453
    421454/** @name Protocol structures
    422  * These convenience structures are here as they are portable ways of dealing
    423  * with various protocols.
     455 * These convenience structures provide portable versions of the headers
     456 * for a variety of protocols.
    424457 * @{
    425458 */
    … …  
    456489typedef struct libtrace_ip6_ext
    457490{
    458         uint8_t nxt;
    459         uint8_t len;
     491        uint8_t nxt;    /**< Next header */
     492        uint8_t len;    /**< Length of the current header */
    460493} PACKED libtrace_ip6_ext_t;
    461494
    462 /** Generic IPv6 header structure */
     495/** Generic IPv6 header structure
     496 *
     497 * @note The flow label field also includes the Version and Traffic Class
     498 * fields, because we haven't figured out a nice way to deal with fields
     499 * crossing byte boundaries on both Big and Little Endian machines */
    463500typedef struct libtrace_ip6
    464501{
    465     uint32_t flow;
     502    uint32_t flow;                      /**< Flow label */
    466503    uint16_t plen;                      /**< Payload length */
    467504    uint8_t nxt;                        /**< Next header */
    468505    uint8_t hlim;                       /**< Hop limit */
    469     struct in6_addr ip_src;             /**< source address */
    470     struct in6_addr ip_dst;             /**< dest address */
     506    struct in6_addr ip_src;             /**< Source address */
     507    struct in6_addr ip_dst;             /**< Destination address */
    471508} PACKED libtrace_ip6_t;
    472509
    … …  
    524561    struct
    525562    {
    526       uint16_t  id;
    527       uint16_t  sequence;
     563      uint16_t  id;             /**< ID of the Echo request */
     564      uint16_t  sequence;       /**< Sequence number of the Echo request */
    528565    } echo;                     /**< Echo Datagram */
    529566    uint32_t    gateway;        /**< Gateway Address */
    530567    struct
    531568    {
    532       uint16_t  unused;
    533       uint16_t  mtu;
     569      uint16_t  unused;         /**< Unused */
     570      uint16_t  mtu;            /**< Next-hop MTU */
    534571    } frag;                     /**< Path MTU Discovery */
    535572  } un;                         /**< Union for Payloads of Various ICMP Codes */
    … …  
    542579  uint8_t dsap;                 /**< Destination Service Access Point */
    543580  uint8_t ssap;                 /**< Source Service Access Point */
    544   uint8_t control;
     581  uint8_t control;              /**< Control field */
    545582/* SNAP */
    546583  LT_BITFIELD32 oui:24;         /**< Organisationally Unique Identifier (scope)*/
    … …  
    590627/** Captured UNI cell.
    591628 *
    592  * Endance don't capture the HEC, presumably to keep alignment.  This
    593  * version of the \ref libtrace_atm_cell  is used when dealing with dag
     629 * Endace don't capture the HEC, presumably to keep alignment.  This
     630 * version of the \ref libtrace_atm_cell is used when dealing with DAG
    594631 * captures of uni cells.
    595632 *
    … …  
    606643/** Captured NNI cell.
    607644 *
    608  * Endance don't capture the HEC, presumably to keep alignment.  This
    609  * version of the \ref libtrace_atm_nni_cell  is used when dealing with dag
     645 * Endace don't capture the HEC, presumably to keep alignment.  This
     646 * version of the \ref libtrace_atm_nni_cell is used when dealing with DAG
    610647 * captures of nni cells.
    611648 *
    … …  
    645682typedef struct libtrace_80211_t {
    646683#if BYTE_ORDER == LITTLE_ENDIAN
    647         LT_BITFIELD32      protocol:2;
    648         LT_BITFIELD32      type:2;
    649         LT_BITFIELD32      subtype:4;
     684        LT_BITFIELD32      protocol:2;  /**< Protocol Version */
     685        LT_BITFIELD32      type:2;      /**< Frame Type */
     686        LT_BITFIELD32      subtype:4;   /**< Frame Subtype */
    650687#else
    651         LT_BITFIELD32      subtype:4;
    652         LT_BITFIELD32      type:2;
    653         LT_BITFIELD32      protocol:2;
     688        LT_BITFIELD32      subtype:4;   /**< Frame Subtype */
     689        LT_BITFIELD32      type:2;      /**< Frame Type */
     690        LT_BITFIELD32      protocol:2;  /**< Protocol Version */
    654691#endif
    655692
    … …  
    659696        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
    660697        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
    661         LT_BITFIELD32      power:1;
    662         LT_BITFIELD32      more_data:1;
    663         LT_BITFIELD32      wep:1;
    664         LT_BITFIELD32      order:1;
     698        LT_BITFIELD32      power:1;     /**< Power Management mode */
     699        LT_BITFIELD32      more_data:1; /**< More data is buffered at station */
     700        LT_BITFIELD32      wep:1;       /**< WEP encryption indicator */
     701        LT_BITFIELD32      order:1;     /**< Strictly-Ordered class indicator */
    665702#else
    666         LT_BITFIELD32      order:1;
    667         LT_BITFIELD32      wep:1;
    668         LT_BITFIELD32      more_data:1;
    669         LT_BITFIELD32      power:1;
     703        LT_BITFIELD32      order:1;     /**< Strictly-Ordered class indicator */
     704        LT_BITFIELD32      wep:1;       /**< WEP encryption indicator */
     705        LT_BITFIELD32      more_data:1; /**< More data is buffered at station */
     706        LT_BITFIELD32      power:1;     /**< Power Management mode */
    670707        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
    671708        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
    … …  
    673710        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
    674711#endif
    675         uint16_t     duration;
    676         uint8_t      mac1[6];
    677         uint8_t      mac2[6];
    678         uint8_t      mac3[6];
    679         uint16_t     SeqCtl;
    680         uint8_t      mac4[6];
     712        uint16_t     duration;  /**< Duration value for NAV calculation */
     713        uint8_t      mac1[6];   /**< MAC Address 1 */
     714        uint8_t      mac2[6];   /**< MAC Address 2 */
     715        uint8_t      mac3[6];   /**< MAC Address 3 */
     716        uint16_t     SeqCtl;    /**< Sequence Control */       
     717        uint8_t      mac4[6];   /**< MAC Address 4 */
    681718} PACKED libtrace_80211_t;
    682719
    … …  
    716753 */
    717754
    718 /** Create a trace file from a URI
     755/** Create an input trace from a URI
    719756 *
    720  * @param uri containing a valid libtrace URI
    721  * @return an opaque pointer to a libtrace_t
    722  *
    723  * Valid URI's are:
     757 * @param uri A valid libtrace URI to be opened
     758 * @return An opaque pointer to a libtrace_t
     759 *
     760 * Some valid URI's are:
    724761 *  - erf:/path/to/erf/file
    725762 *  - erf:-  (stdin)
    … …  
    730767 *  - rt:hostname
    731768 *  - rt:hostname:port
    732  *  - rtclient:hostname (deprecated)
    733  *  - rtclient:hostname:port (deprecated)
    734  *
    735  *  If an error occured when attempting to open the trace file, an error
    736  *  trace is returned and trace_get_error should be called to find out
    737  *  if an error occured, and what that error was.  The trace is created in the
    738  *  configuration state, you must call trace_start to start the capture.
     769 *
     770 *  If an error occured when attempting to open the trace file, a
     771 *  trace is still returned so trace_is_err() should be called to find out
     772 *  if an error occured. The trace is created in the configuration state, you
     773 *  must call trace_start before attempting to read packets from the trace.
    739774 */
    740775DLLEXPORT libtrace_t *trace_create(const char *uri);
    … …  
    742777/** Creates a "dummy" trace file that has only the format type set.
    743778 *
    744  * @return an opaque pointer to a (sparsely initialised) libtrace_t
    745  *
    746  * IMPORTANT: Do not attempt to call trace_read_packet or other such functions
    747  * with the dummy trace. Its intended purpose is to act as a packet->trace for
    748  * libtrace_packet_t's that are not associated with a libtrace_t structure.
     779 * @param uri A valid (but fake) URI indicating the format of the dummy trace that is to be created.
     780 * @return An opaque pointer to a (sparsely initialised) libtrace_t
     781 *
     782 * Only the format portion of the uri parameter matters - the 'file' being
     783 * opened does not have to exist.
     784 *
     785 * @note IMPORTANT: Do not attempt to call trace_read_packet or other such
     786 * functions with the dummy trace. Its intended purpose is to provide access
     787 * to the format functions where the original trace may no longer exist or is
     788 * not the correct format, e.g. reading ERF packets from an RT input.
    749789 */
    750790DLLEXPORT libtrace_t *trace_create_dead(const char *uri);
    … …  
    752792/** Creates a trace output file from a URI.
    753793 *
    754  * @param uri   the uri string describing the output format and destination
    755  * @return an opaque pointer to a libtrace_output_t
    756  *
    757  * Valid URI's are:
     794 * @param uri The uri string describing the output format and destination
     795 * @return An opaque pointer to a libtrace_output_t
     796 *
     797 * Valid URIs include:
    758798 *  - erf:/path/to/erf/file
    759799 *  - pcap:/path/to/pcap/file
    760  *  - wtf:/path/to/wtf/file
    761  *
    762  *  If an error occured when attempting to open the output trace, NULL is returned
    763  *  and trace_errno is set. Use trace_perror_output() to get more information
     800 *
     801 *  If an error occured when attempting to open the output trace, a trace is
     802 *  still returned but trace_errno will be set. Use trace_is_err_out() and
     803 *  trace_perror_output() to get more information.
    764804 */
    765805DLLEXPORT libtrace_out_t *trace_create_output(const char *uri);
    766806
    767 /** Start the capture
     807/** Start an input trace
    768808 * @param libtrace      The trace to start
    769809 * @return 0 on success, -1 on failure
    770810 *
    771  * This does the actual work with starting the trace capture, and applying
    772  * all the config options.  This may fail.
     811 * This does the actual work of starting the input trace and applying
     812 * all the config options.  This may fail, returning -1. The libtrace error
     813 * handling functions can be used to get more information about what
     814 * specifically went wrong.
    773815 */
    774816DLLEXPORT int trace_start(libtrace_t *libtrace);
    775817
    776 /** Pause the capture
     818/** Pauses an input trace
    777819 * @param libtrace      The trace to pause
    778820 * @return 0 on success, -1 on failure
    779821 *
    780  * This stops a capture in progress and returns you to the configuration
    781  * state.  Any packets that arrive after trace_pause() has been called
    782  * will be discarded.  To resume capture, call trace_start().
     822 * This stops an input trace that is in progress and returns you to the
     823 * configuration state.  Any packets that arrive on a live capture after
     824 * trace_pause() has been called will be discarded.  To resume the trace, call
     825 * trace_start().
    783826 */
    784827DLLEXPORT int trace_pause(libtrace_t *libtrace);
    … …  
    788831 * @return 0 on success, -1 on failure
    789832 *
    790  * This does the actual work with starting a trace for write.  This generally
    791  * creates the file.
     833 * This does the actual work with starting a trace capable of writing packets. 
     834 * This generally creates the output file.
    792835 */
    793836DLLEXPORT int trace_start_output(libtrace_out_t *libtrace);
    794837
    795 /** Valid trace capture options */
     838/** Valid configuration options for input traces */
    796839typedef enum {
    797         TRACE_OPTION_SNAPLEN,   /**< Number of bytes captured */
    798         TRACE_OPTION_PROMISC,   /**< Capture packets to other hosts */
    799         TRACE_OPTION_FILTER,    /**< Apply this filter to all packets */
    800         TRACE_OPTION_META_FREQ, /**< Frequency of meta-data information, e.g. DUCK packets */
    801         /** trace_event ignores gaps between packets when reading traces off disk */
     840        /** Maximum number of bytes to be captured for any given packet */
     841        TRACE_OPTION_SNAPLEN,   
     842
     843        /** If enabled, places a live capture interface into promiscuous mode */
     844        TRACE_OPTION_PROMISC,   
     845
     846        /** Apply this filter to all packets read from this trace */
     847        TRACE_OPTION_FILTER,   
     848
     849        /** Defines the frequency of meta-data reporting, e.g. DUCK packets */
     850        TRACE_OPTION_META_FREQ,
     851
     852        /* If enabled, the libtrace event API will ignore time gaps between
     853         * packets when reading from a trace file */
    802854        TRACE_OPTION_EVENT_REALTIME
    803855} trace_option_t;
    804856
    805857/** Sets an input config option
    806  * @param libtrace      the trace object to apply the option to
    807  * @param option        the option to set
    808  * @param value         the value to set the option to
     858 * @param libtrace      The trace object to apply the option to
     859 * @param option        The option to set
     860 * @param value         The value to set the option to
    809861 * @return -1 if option configuration failed, 0 otherwise
    810862 * This should be called after trace_create, and before trace_start
    … …  
    814866                void *value);
    815867
     868/** Valid configuration options for output traces */
    816869typedef enum {
    817         TRACE_OPTION_OUTPUT_FILEFLAGS, /**< File flags to open the trace file
    818                                         * with.  eg O_APPEND
    819                                         */
    820         TRACE_OPTION_OUTPUT_COMPRESS   /**< Compression level, eg 6. */
     870        /** File flags to use when opening an output file, e.g. O_APPEND */
     871        TRACE_OPTION_OUTPUT_FILEFLAGS,
     872        /** Compression level: 0 = no compression, 1 = faster compression,
     873         * 9 = better compression */
     874        TRACE_OPTION_OUTPUT_COMPRESS   
    821875} trace_option_output_t;
    822876
    823877/** Sets an output config option
    824878 *
    825  * @param libtrace      the output trace object to apply the option to
    826  * @param option        the option to set
    827  * @param value         the value to set the option to
     879 * @param libtrace      The output trace object to apply the option to
     880 * @param option        The option to set
     881 * @param value         The value to set the option to
    828882 * @return -1 if option configuration failed, 0 otherwise
    829883 * This should be called after trace_create_output, and before
    … …  
    835889                );
    836890
    837 /** Close a trace file, freeing up any resources it may have been using
     891/** Close an input trace, freeing up any resources it may have been using
     892 *
     893 * @param trace         The input trace to be destroyed
    838894 *
    839895 */
    840896DLLEXPORT void trace_destroy(libtrace_t *trace);
    841897
    842 /** Close a trace file, freeing up any resources it may have been using
    843  * @param trace         trace file to be destroyed
     898/** Close a dummy trace file, freeing up any resources it may have been using
     899 * @param trace         The dummy trace to be destroyed
    844900 */
    845901DLLEXPORT void trace_destroy_dead(libtrace_t *trace);
    846902
    847 /** Close a trace output file, freeing up any resources it may have been using
    848  * @param trace         the output trace file to be destroyed
     903/** Close an output trace, freeing up any resources it may have been using
     904 * @param trace         The output trace to be destroyed
    849905 */
    850906DLLEXPORT void trace_destroy_output(libtrace_out_t *trace);
    851907
    852908/** Check (and clear) the current error state of an input trace
    853  * @param trace         the trace file to check the error state on
    854  * @return Error report
     909 * @param trace         The input trace to check the error state on
     910 * @return The current error status and message
     911 *
    855912 * This reads and returns the current error state and sets the current error
    856913 * to "no error".
    … …  
    858915DLLEXPORT libtrace_err_t trace_get_err(libtrace_t *trace);
    859916
    860 /** Return if there is an error
    861  * @param trace         the trace file to check the error state on
    862  * This does not clear the error status, and only returns true or false.
     917/** Indicate if there has been an error on an input trace
     918 * @param trace         The input trace to check the error state on
     919 * @return true if an error has occurred, false otherwise
     920 *
     921 * @note This does not clear the error status, and only returns true or false.
    863922 */
    864923DLLEXPORT bool trace_is_err(libtrace_t *trace);
    865924
    866 /** Output an error message to stderr and clear the error status.
    867  * @param trace         the trace with the error to output
    868  * @param msg           the message to prefix to the error
     925/** Outputs the error message for an input trace to stderr and clear the error
     926 * status.
     927 * @param trace         The input trace with the error to output
     928 * @param msg           The message to prepend to the error
     929 *
    869930 * This function does clear the error status.
    870931 */
    871932DLLEXPORT void trace_perror(libtrace_t *trace, const char *msg,...) PRINTF(2,3);
    872933
    873 /** Check (and clear) the current error state of an output trace
    874  * @param trace         the output trace file to check the error state on
    875  * @return Error report
     934/** Checks (and clears) the current error state for an output trace
     935 * @param trace         The output trace to check the error state on
     936 * @return The current error status and message
     937 *
    876938 * This reads and returns the current error state and sets the current error
    877939 * to "no error".
    … …  
    879941DLLEXPORT libtrace_err_t trace_get_err_output(libtrace_out_t *trace);
    880942
    881 /** Return if there is an error
    882  * @param trace         the trace file to check the error state on
     943/** Indicates if there is an error on an output trace
     944 * @param trace         The output trace to check the error state on
     945 * @return true if an error has occurred, false otherwise.
     946 *
    883947 * This does not clear the error status, and only returns true or false.
    884948 */
    885949DLLEXPORT bool trace_is_err_output(libtrace_out_t *trace);
    886950
    887 /** Output an error message to stderr and clear the error status.
    888  * @param trace         the trace with the error to output
    889  * @param msg           the message to prefix to the error
     951/** Outputs the error message for an output trace to stderr and clear the error
     952 * status.
     953 * @param trace         The output trace with the error to output
     954 * @param msg           The message to prepend to the error
    890955 * This function does clear the error status.
    891956 */
    … …  
    893958        PRINTF(2,3);
    894959
    895 /** Return the number of captured packets
     960/** Returns the number of packets observed on an input trace.
    896961 * Includes the number of packets counted as early as possible, before
    897962 * filtering, and includes dropped packets.
    898963 *
    899  * @param trace         Trace to examine
    900  * @returns number of packets seen at the capture point before filtering.
    901  *
    902  * If this is not known, this will return UINT64_MAX
     964 * @param trace         The input trace to examine
     965 * @returns The number of packets seen at the capture point before filtering.
     966 *
     967 * If the number is not known, this function will return UINT64_MAX
    903968 */
    904969DLLEXPORT
    905970uint64_t trace_get_received_packets(libtrace_t *trace);
    906971
    907 /** Return the number of filtered packets
    908  * Returns the number of packets that were captured, but discarded for not
    909  * matching a trace filter.  This includes packets
    910  *
    911  * @param trace         Trace file to examine
    912  * @returns the number of packets that were successfully captured, but filtered
    913  *
    914  * If this is not known, this will return UINT64_MAX
     972/** Returns the number of packets that were captured, but discarded for not
     973 * matching a provided filter.
     974 *
     975 * @param trace         The input trace to examine
     976 * @returns The number of packets that were successfully captured, but filtered
     977 *
     978 * If the number is not known, this function will return UINT64_MAX
    915979 */
    916980DLLEXPORT
    917981uint64_t trace_get_filtered_packets(libtrace_t *trace);
    918982
    919 /** Return the number of packets that have been dropped for lack of packets
    920  * @param trace         Trace file to examine
     983/** Returns the number of packets that have been dropped on an input trace due
     984 * to lack of buffer space on the capturing device.
     985 *
     986 * @param trace         The input trace to examine
    921987 * @returns The number of packets captured, but dropped due to buffer overruns
     988 *
     989 * If the number is not known, this function will return UINT64_MAX
    922990 */
    923991DLLEXPORT
    924992uint64_t trace_get_dropped_packets(libtrace_t *trace);
    925993
    926 /** Return the number of packets that have been returned to library user
    927  * @param trace         Trace file to examine
    928  * @returns The number of packets returned to the user of the library.
     994/** Returns the number of packets that have been read from the input trace using
     995 * trace_read_packet().
     996 *
     997 * @param trace         The input trace to examine
     998 * @returns The number of packets that have been read by the libtrace user.
     999 *
     1000 * If the number is not known, this function will return UINT64_MAX
    9291001 */
    9301002DLLEXPORT
    … …  
    9421014/** Create a new packet object
    9431015 *
    944  * @return a pointer to an initialised libtrace_packet_t object
     1016 * @return A pointer to an initialised libtrace_packet_t object
    9451017 */
    9461018DLLEXPORT libtrace_packet_t *trace_create_packet(void);
    9471019
    948 /** Copy a packet
    949  * @param packet        the source packet to copy
    950  * @return a new packet which has the same content as the source packet
     1020/** Copy a packet object
     1021 * @param packet        The source packet to copy
     1022 * @return A new packet which has the same content as the source packet
     1023 *
    9511024 * @note This always involves a copy, which can be slow.  Use of this
    9521025 * function should be avoided where possible.
     1026 *
    9531027 * @par The reason you would want to use this function is that a zerocopied
    954  * packet from a device is using the devices memory which may be a limited
    955  * resource.  Copying the packet will cause it to be copied into the systems
    956  * memory.
     1028 * packet from a device will be stored using memory owned by the device which
     1029 * may be a limited resource. Copying the packet will ensure that the packet
     1030 * is now stored in memory owned and managed by libtrace.
    9571031 */
    9581032DLLEXPORT libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet);
    9591033
    9601034/** Destroy a packet object
    961  *
    962  * sideeffect: sets packet to NULL
     1035 * @param packet        The packet to be destroyed
     1036 *
    9631037 */
    9641038DLLEXPORT void trace_destroy_packet(libtrace_packet_t *packet);
    9651039
    9661040
    967 /** Read one packet from the trace
    968  *
    969  * @param trace         the libtrace opaque pointer
    970  * @param packet        the packet opaque pointer
    971  * @return 0 on EOF, negative value on error, number of bytes read when
    972  * successful.
    973  *
    974  * @note the number of bytes read is usually (but not always) the same as
     1041/** Read the next packet from an input trace
     1042 *
     1043 * @param trace         The libtrace opaque pointer for the input trace
     1044 * @param packet        The packet opaque pointer
     1045 * @return 0 on EOF, negative value on error, number of bytes read when successful.
     1046 *
     1047 * @note The number of bytes read is usually (but not always) the same as
    9751048 * trace_get_framing_length()+trace_get_capture_length() depending on the
    9761049 * trace format.
    977  * @note the trace must have been started with trace_start before calling
     1050 *
     1051 * @note The trace must have been started with trace_start before calling
    9781052 * this function
     1053 *
     1054 * @note When reading from a live capture, this function will block until a
     1055 * packet is observed on the capture interface. The libtrace event API
     1056 * (e.g. trace_event()) should be used if non-blocking operation is required.
    9791057 */
    9801058DLLEXPORT int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet);
    … …  
    9841062 */
    9851063typedef enum {
    986         TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
    987         TRACE_EVENT_SLEEP,      /**< Sleep for some time */
    988         TRACE_EVENT_PACKET,     /**< packet has arrived */
    989         TRACE_EVENT_TERMINATE   /**< End of trace */
     1064        TRACE_EVENT_IOWAIT,     /**< Wait on the given file descriptor */
     1065        TRACE_EVENT_SLEEP,      /**< Sleep for the given amount of time */
     1066        TRACE_EVENT_PACKET,     /**< Packet has been read from input trace */
     1067        TRACE_EVENT_TERMINATE   /**< End of input trace */
    9901068} libtrace_event_t;
    9911069
    9921070/** Structure returned by libtrace_event explaining what the current event is */
    9931071typedef struct libtrace_eventobj_t {
    994         libtrace_event_t type; /**< event type (iowait,sleep,packet) */
    995         int fd;                /**< if IOWAIT, the fd to sleep on */
    996         double seconds;        /**< if SLEEP, the amount of time to sleep for
    997                                 */
    998         int size;              /**< if PACKET, the value returned from
    999                                 *  trace_read_packet
    1000                                 */
     1072        libtrace_event_t type; /**< Event type (iowait,sleep,packet) */
     1073       
     1074        /** If the event is IOWAIT, the file descriptor to wait on */
     1075        int fd;               
     1076        /** If the event is SLEEP, the amount of time to sleep for in seconds */
     1077        double seconds;       
     1078        /** If the event is PACKET, the value returned by trace_read_packet() */
     1079        int size;
    10011080} libtrace_eventobj_t;
    10021081
    1003 /** Processes the next libtrace event
    1004  * @param trace the libtrace opaque pointer
    1005  * @param packet the libtrace_packet opaque pointer
    1006  * @return libtrace_event struct containing the type, and potential
    1007  *      fd or seconds to sleep on
     1082/** Processes the next libtrace event from an input trace.
     1083 * @param trace The libtrace opaque pointer for the input trace
     1084 * @param packet The libtrace_packet opaque pointer to use for reading packets
     1085 * @return A libtrace_event struct containing the event type and details of the event.
    10081086 *
    10091087 * Type can be:
    1010  *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
    1011  *  TRACE_EVENT_SLEEP   Next event in seconds
    1012  *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
     1088 *  TRACE_EVENT_IOWAIT  Waiting on I/O on a file descriptor
     1089 *  TRACE_EVENT_SLEEP   Wait a specified amount of time for the next event
     1090 *  TRACE_EVENT_PACKET  Packet was read from the trace
    10131091 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
    10141092 */
    … …  
    10191097/** Write one packet out to the output trace
    10201098 *
    1021  * @param trace         the libtrace_out opaque pointer
    1022  * @param packet        the packet opaque pointer
    1023  * @return the number of bytes written out, if zero or negative then an error has occured.
     1099 * @param trace         The libtrace_out opaque pointer for the output trace
     1100 * @param packet        The packet opaque pointer of the packet to be written
     1101 * @return The number of bytes written out, if zero or negative then an error has occured.
    10241102 */
    10251103DLLEXPORT int trace_write_packet(libtrace_out_t *trace, libtrace_packet_t *packet);
    … …  
    10321110 * A packet is divided up into several "layers.":
    10331111 *
    1034  * @li Framing header -- This is the header in a tracefile, or as captured from the network.
    1035  * generally this includes capture lengths, wire lengths, timestamps, direction information and
    1036  * any other metadata that is part of the capture format. 
     1112 * @li Framing header -- This is the header provided by the capture format
     1113 * itself rather than anything that was sent over the network. This provides
     1114 * basic details about the packet record including capture lengths, wire
     1115 * lengths, timestamps, direction information and any other metadata that is
     1116 * part of the capture format. 
    10371117 *
    1038  * @li Metadata header (optional) -- A header containing metadata about a packet that was captured,
    1039  * but the metadata was not transmitted over the wire.  Some examples include
    1040  * RadioTap and Linux_sll headers.  This can be retrieved by
    1041  * trace_get_packet_meta(), or skipped using trace_get_payload_from_meta().
    1042  * There may be multiple "metadata" headers on a packet.
    1043  *
    1044  * @li Layer 2/Link layer/Datalink header -- This can be retrieved by trace_get_layer2(), or
    1045  * skipped using trace_get_payload_from_layer2().
    1046  *
    1047  * @li Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3().  As a convenience
    1048  * trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6 header.
    1049  *
    1050  * @li Layer 5/transport -- These are protocols carried in IPv4/IPv6 frames.  These can be
    1051  * retrieved using trace_get_transport().
     1118 * @li Metadata header (optional) -- A header containing metadata about a
     1119 * packet that was captured, but the metadata was not transmitted over the
     1120 * wire.  Some examples include RadioTap and Linux_sll headers.  This can be
     1121 * retrieved by trace_get_packet_meta(), or skipped using
     1122 * trace_get_payload_from_meta(). There may be multiple "metadata" headers on
     1123 * a packet.
     1124 *
     1125 * @li Layer 2/Link layer/Datalink header -- This can be retrieved by
     1126 * trace_get_layer2(), or skipped using trace_get_payload_from_layer2().
     1127 *
     1128 * @li Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3().  As a
     1129 * convenience trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6
     1130 * header.
     1131 *
     1132 * @li Layer 5/transport -- These are protocols carried in IPv4/IPv6 frames.
     1133 * These can be retrieved using trace_get_transport().
    10521134 *
    10531135 * @{
    … …  
    10601142 * Use this function instead of the deprecated trace_get_link().
    10611143 *
    1062  * @param packet the packet pointer
    1063  * @param[out] linktype the linktype of the returned pointer
    1064  * @param[out] remaining the capture length (the number of captured bytes from
     1144 * @param packet The packet to get the buffer from
     1145 * @param[out] linktype The linktype of the returned pointer
     1146 * @param[out] remaining The capture length (the number of captured bytes from
    10651147 * the returned pointer)
    1066  * @return a pointer to the first byte of the packet
     1148 * @return A pointer to the first byte of the packet
    10671149 */
    10681150DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
    10691151                libtrace_linktype_t *linktype, uint32_t *remaining);
    10701152
    1071 /** get a pointer to the link layer
    1072  * @param packet        the packet opaque pointer
    1073  *
    1074  * @return a pointer to the link layer, or NULL if there is no link layer
     1153/** Get a pointer to the link layer for a given packet
     1154 * @param packet        The packet to get the link layer for
     1155 *
     1156 * @return A pointer to the link layer, or NULL if there is no link layer
    10751157 *
    10761158 * @deprecated This function is deprecated: Use trace_get_packet_buffer() or
    10771159 * one of the trace_get_layer*() functions instead.
    1078  * @note you should call trace_get_link_type to find out what type of link
    1079  * layer this is
     1160 * @note You should call trace_get_link_type to find out what type of link
     1161 * layer has been returned to you.
    10801162 */
    10811163DLLEXPORT SIMPLE_FUNCTION DEPRECATED
    10821164void *trace_get_link(const libtrace_packet_t *packet);
    10831165
    1084 /** get a pointer to the IPv4 header (if any)
    1085  * @param packet        the packet opaque pointer
    1086  *
    1087  * @return a pointer to the IPv4 header, or NULL if there is no IPv4 header
     1166/** Get a pointer to the IPv4 header (if any) for a given packet
     1167 * @param packet        The packet to get the IPv4 header for
     1168 *
     1169 * @return A pointer to the IPv4 header, or NULL if there is no IPv4 header
     1170 *
     1171 * If a partial IP header is present, i.e. the packet has been truncated before
     1172 * the end of the IP header, this function will return NULL.
    10881173 *
    10891174 * You should consider using \ref trace_get_layer3 instead of this function.
Note: See TracChangeset for help on using the changeset viewer.