Changeset b53d019

Timestamp:

09/17/15 13:24:51 (5 years ago)

Author:

Shane Alcock <salcock@…>

Branches:

4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, 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:

9a0e118

Parents:

76c86fb

Message:

Tidy up some documentation in libtrace.h

File:

• lib/libtrace.h.in (modified) (16 diffs)

lib/libtrace.h.in

@@ -2 +2 @@
  * This file is part of libtrace
  *
- * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton, 
+ * Copyright (c) 2007-2015 The University of Waikato, Hamilton,
  * New Zealand.
  *
- * Authors: Daniel Lawson 
+ * Authors: Daniel Lawson
  *          Perry Lorier
- *          Shane Alcock 
- *          
+ *          Shane Alcock
+ *          Richard Sanger
+ *
  * All rights reserved.
  *
- * This code has been developed by the University of Waikato WAND 
+ * This code has been developed by the University of Waikato WAND
  * research group. For further information please see http://www.wand.net.nz/
  *
@@ -42 +43 @@
  * @author Perry Lorier
  * @author Shane Alcock
+ * @author Richard Sanger
  *
  * @version $Id$
  *
- * This library provides a per packet interface into a trace file, or a live 
+ * This library provides a per packet interface into a trace file, or a live
  * captures.  It supports ERF, DAG cards, PCAP, Linux and BSD native sockets,
  * legacy ERF formats etc.
  *
  * @par Usage
- * See the example/ directory in the source distribution for some simple 
+ * See the example/ directory in the source distribution for some simple
  * examples
  *
  * @par Linking
  * To use this library you need to link against libtrace by passing -ltrace
- * to your linker. You may also need to link against a version of libpcap 
- * and of zlib which are compiled for largefile support (if you wish to access
- * traces larger than 2 GB). This is left as an exercise for the reader. Debian
- * Woody, at least, does not support large file offsets.
+ * to your linker.
+ *
+ * See libtrace_parallel.h for a description of the parallel API that allows
+ * programmers to spread packet processing across multiple threads.
  *
  */
@@ -240 +242 @@
 #endif
 
-        
+
 /** Opaque structure holding information about an output trace */
 typedef struct libtrace_out_t libtrace_out_t;
-        
+
 /** Opaque structure holding information about a trace */
 typedef struct libtrace_t libtrace_t;
-        
+
 /** Opaque structure holding information about a bpf filter */
 typedef struct libtrace_filter_t libtrace_filter_t;
@@ -312 +314 @@
          * DLT */
         TRACE_DLT_ERROR = -1,
-        
-        /** pcap documents this as having the Address Family value in host byte order as the 
-          * framing.  Ugly? Yes.
+
+        /** pcap documents this as having the Address Family value in host 
+          * byte order as the framing.  Ugly? Yes.
           */
         TRACE_DLT_NULL = 0, 
@@ -320 +322 @@
         TRACE_DLT_PPP = 9,
         TRACE_DLT_ATM_RFC1483 = 11,
-        
-        /** Ok, so OpenBSD has a different value for DLT_RAW as the rest of the planet, so detect
-          * this.  When reading to/from files we should be using TRACE_DLT_LINKTYPE_RAW instead.
-          * When talking about DLT's inside libtrace tho, we should be using /these/ DLT's.
-          */
+
+        /** Ok, so OpenBSD has a different value for DLT_RAW as the rest of
+         * the planet, so detect this.  When reading to/from files we should
+         * be using TRACE_DLT_LINKTYPE_RAW instead. When talking about DLT's
+         * inside libtrace tho, we should be using /these/ DLT's.
+         */
 #ifdef __OpenBSD__
         TRACE_DLT_OPENBSD_LOOP=12,
-        TRACE_DLT_RAW = 14,     
+        TRACE_DLT_RAW = 14
 #else
         TRACE_DLT_RAW = 12,
@@ -625 +628 @@
 } PACKED libtrace_ip6_ext_t;
 
+/** IPv6 fragmentation header */
 typedef struct libtrace_ip6_frag 
 {
@@ -717 +721 @@
 } PACKED libtrace_icmp_t;
 
+/** Generic ICMPv6 header structure */
 typedef struct libtrace_icmp6 {
   uint8_t type;         /**< Message Type */
@@ -1091 +1096 @@
 } PACKED libtrace_ospf_router_lsa_v2_t;
 
+/** OSPF message types */
 typedef enum {
         TRACE_OSPF_HELLO = 1,           /**< OSPF Hello */
@@ -1099 +1105 @@
 } libtrace_ospf_types_t;
 
+/** OSPF link state acknowledgement types */
 typedef enum {
         TRACE_OSPF_LS_ROUTER = 1,       /**< OSPF Router LSA */
@@ -1191 +1198 @@
  *  - erf:/path/to/erf/file
  *  - erf:-  (stdin)
- *  - dag:/dev/dagcard                  
+ *  - dag:/dev/dagcard
  *  - pcapint:pcapinterface                (eg: pcap:eth0)
  *  - pcap:/path/to/pcap/file
@@ -1383 +1390 @@
  * Statistic counters are cumulative from the time the trace is started.
  * Trace pause will reset the counters, to zero.
- * Always check \a{field}_valid is set before attempting to read the stored value.
+ * Always check \a{field}_valid is set before attempting to read the stored
+ * value.
  *
  * @note Always allocate this structure using trace_create_statistics().
@@ -1401 +1409 @@
 
         /* These must all be uint64_t's, match this order with the X macro */
-        uint64_t accepted;
-        /**< The number of packets that have been read from the input trace
+        /** The number of packets that have been read from the input trace
          * using trace_read_packet(). In the parallel framework this may include
          * some packets waiting in a batch yet to be seen by the user's
@@ -1412 +1419 @@
          * @note This field replaces trace_get_accepted_packets()
          */
-        uint64_t filtered;
-        /**< The number of packets that were captured, but discarded for not
+        uint64_t accepted;
+
+        /** The number of packets that were captured, but discarded for not
          * matching a provided filter.
          *
          * @note This field replaces trace_get_filtered_packets()
          */
-        uint64_t received;
-        /**< The total number of good packets which have been recevied. Including
+        uint64_t filtered;
+
+        /** The total number of good packets which have been recevied. Including
          * those which are dropped and filtered. This does not include errors.
          *
@@ -1427 +1436 @@
          * @note This field replaces trace_get_received_packets()
          */
-        uint64_t dropped;
-        /**< The number of packets that have been dropped on an input trace
+        uint64_t received;
+
+        /** The number of packets that have been dropped on an input trace
          * due to lack of buffer space on the capturing device. This does not
          * included errored packets which are dropped directly by the card.
@@ -1434 +1444 @@
          * @note This field replaces trace_get_dropped_packets()
          */
-        uint64_t captured;
-        /**< The number of received packets that have not been dropped. This
+        uint64_t dropped;
+
+        /** The number of received packets that have not been dropped. This
          * includes filtered packets.
          *
@@ -1443 +1454 @@
          *       not yet included in accepted.
          */
-        uint64_t errors;
-        /**< The number of packets that have been discarded by the network card
+        uint64_t captured;
+
+        /** The number of packets that have been discarded by the network card
          * because they are invalid. That includes FCS mismatches, incorrect
          * packet lengths etc.
          */
+        uint64_t errors;
 } libtrace_stat_t;