Changeset 83445f0 for lib


Ignore:
Timestamp:
05/11/06 16:57:27 (15 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:
da34e20
Parents:
4e65f42
Message:

Tidied up some of the documentation
Removed the out-dated trace_get_output_format function

Location:
lib
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • lib/libtrace.h.in

    r3fcb8b4 r83445f0  
    140140typedef struct libtrace_filter_t libtrace_filter_t;
    141141
    142 /** if a packet has memory allocated
     142/** If a packet has memory allocated
    143143 * If the packet has allocated it's own memory it's buffer_control should
    144144 * be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be
    … …  
    152152        TRACE_CTRL_EXTERNAL='e'
    153153} buf_control_t;
    154 /** Structure holding information about a packet */
     154/** The size of a packet's buffer when managed by libtrace */
    155155#define LIBTRACE_PACKET_BUFSIZE 65536
    156156
    157 /** The libtrace structure, applications shouldn't be meddling around in here
     157/** The libtrace packet structure, applications shouldn't be
     158 * meddling around in here
    158159 */
    159160typedef struct libtrace_packet_t {
    … …  
    184185        /** Unknown config option */
    185186        TRACE_ERR_UNKNOWN_OPTION= -3,
    186         /** Option known, but unsupported by this format */
    187         TRACE_ERR_OPTION_UNAVAIL= -6,
    188187        /** This output uri cannot write packets of this type */
    189188        TRACE_ERR_NO_CONVERSION = -4,
    190189        /** This packet is corrupt, or unusable for the action required */
    191190        TRACE_ERR_BAD_PACKET    = -5,
     191        /** Option known, but unsupported by this format */
     192        TRACE_ERR_OPTION_UNAVAIL= -6,
    192193        /** This feature is unsupported */
    193194        TRACE_ERR_UNSUPPORTED   = -7
    194195};
    195196
     197/** Enumeration of DLT types supported by libtrace */
    196198typedef enum {
    197199        TRACE_DLT_NULL = 0,
    … …  
    203205} libtrace_dlt_t ;
    204206
    205 /** Link layer types
    206  * This enumates the various different link types that libtrace understands
    207  */
     207/** Enumeration of link layer types supported by libtrace */
    208208typedef enum {
    209209       TRACE_TYPE_HDLC_POS = 1,
    210210       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
    211        TRACE_TYPE_ATM,
     211       TRACE_TYPE_ATM,                  /**< ATM frame */
    212212       TRACE_TYPE_AAL5,
    213213       TRACE_TYPE_80211,                /**< 802.11 frames */
    … …  
    241241#endif
    242242
    243 /** Structure for dealing with IP packets */
     243/** Generic IP header structure */
    244244typedef struct libtrace_ip
    245245{
    246246#if BYTE_ORDER == LITTLE_ENDIAN
    247     uint8_t ip_hl:4;            /**< header length */
    248     uint8_t ip_v:4;             /**< version */
     247    uint8_t ip_hl:4;            /**< Header Length */
     248    uint8_t ip_v:4;             /**< Version */
    249249#elif BYTE_ORDER == BIG_ENDIAN
    250     uint8_t ip_v:4;             /**< version */
    251     uint8_t ip_hl:4;            /**< header length */
     250    uint8_t ip_v:4;             /**< Version */
     251    uint8_t ip_hl:4;            /**< Header Length */
    252252#else
    253253#   error "Adjust your <bits/endian.h> defines"
    254254#endif
    255     uint8_t  ip_tos;                    /**< type of service */
    256     uint16_t ip_len;                    /**< total length */
    257     int16_t  ip_id;                     /**< identification */
     255    uint8_t  ip_tos;                    /**< Type of Service */
     256    uint16_t ip_len;                    /**< Total Length */
     257    int16_t  ip_id;                     /**< Identification */
    258258#if BYTE_ORDER == LITTLE_ENDIAN
    259     uint16_t ip_off:12;         /**< fragment offset */
    260     uint16_t ip_mf:1;           /**< more fragments flag */
    261     uint16_t ip_df:1;           /**< dont fragment flag */
    262     uint16_t ip_rf:1;           /**< reserved fragment flag */
     259    uint16_t ip_off:12;         /**< Fragment Offset */
     260    uint16_t ip_mf:1;           /**< More Fragments Flag */
     261    uint16_t ip_df:1;           /**< Dont Fragment Flag */
     262    uint16_t ip_rf:1;           /**< Reserved Fragment Flag */
    263263#elif BYTE_ORDER == BIG_ENDIAN
    264     uint16_t ip_rf:1;
    265     uint16_t ip_df:1;
    266     uint16_t ip_mf:1;
    267     uint16_t ip_off:12;
     264    uint16_t ip_rf:1;           /**< Fragment Offset */
     265    uint16_t ip_df:1;           /**< More Fragments Flag */
     266    uint16_t ip_mf:1;           /**< Dont Fragment Flag */
     267    uint16_t ip_off:12;         /**< Reserved Fragment Flag */
    268268#else
    269269#   error "Adjust your <bits/endian.h> defines"
    270270#endif
    271     uint8_t  ip_ttl;                    /**< time to live */
    272     uint8_t  ip_p;                      /**< protocol */
    273     uint16_t ip_sum;                    /**< checksum */
    274     struct in_addr ip_src;              /**< source address */
    275     struct in_addr ip_dst;              /**< dest address */
     271    uint8_t  ip_ttl;                    /**< Time to Live */
     272    uint8_t  ip_p;                      /**< Protocol */
     273    uint16_t ip_sum;                    /**< Checksum */
     274    struct in_addr ip_src;              /**< Source Address */
     275    struct in_addr ip_dst;              /**< Destination Address */
    276276} PACKED libtrace_ip_t;
    277277
     278/** IPv6 header extension structure */
    278279typedef struct libtrace_ip6_ext
    279280{
    … …  
    282283} PACKED libtrace_ip6_ext_t;
    283284
    284 /** IPv6 header structure */
     285/** Generic IPv6 header structure */
    285286typedef struct libtrace_ip6
    286287{
    … …  
    293294} PACKED libtrace_ip6_t;
    294295
    295 /** Structure for dealing with TCP packets */
     296/** Generic TCP header structure */
    296297typedef struct libtrace_tcp
    297298  {
    … …  
    302303#  if BYTE_ORDER == LITTLE_ENDIAN
    303304    uint8_t res1:4;     /**< Reserved bits */
    304     uint8_t doff:4;     /**< data offset */     
     305    uint8_t doff:4;     /**< Data Offset */     
    305306    uint8_t fin:1;              /**< FIN */
    306307    uint8_t syn:1;              /**< SYN flag */
    … …  
    328329} PACKED libtrace_tcp_t;
    329330
    330 /** UDP Header for dealing with UDP packets */
     331/** Generic UDP header structure */
    331332typedef struct libtrace_udp {
    332333  uint16_t      source;         /**< Source port */
    … …  
    336337} PACKED libtrace_udp_t;
    337338
    338 /** ICMP Header for dealing with icmp packets */
     339/** Generic ICMP header structure */
    339340typedef struct libtrace_icmp
    340341{
    341   uint8_t type;         /**< message type */
    342   uint8_t code;         /**< type sub-code */
    343   uint16_t checksum;            /**< checksum */
     342  uint8_t type;         /**< Message Type */
     343  uint8_t code;         /**< Type Sub-code */
     344  uint16_t checksum;            /**< Checksum */
    344345  union
    345346  {
    … …  
    348349      uint16_t  id;
    349350      uint16_t  sequence;
    350     } echo;                     /**< echo datagram */
    351     uint32_t    gateway;        /**< gateway address */
     351    } echo;                     /**< Echo Datagram */
     352    uint32_t    gateway;        /**< Gateway Address */
    352353    struct
    353354    {
    354355      uint16_t  unused;
    355356      uint16_t  mtu;
    356     } frag;                     /**< path mtu discovery */
    357   } un;                         /**< Union for payloads of various icmp codes */
     357    } frag;                     /**< Path MTU Discovery */
     358  } un;                         /**< Union for Payloads of Various ICMP Codes */
    358359} PACKED libtrace_icmp_t;
    359360
    360 /** LLC/SNAP header */
     361/** Generic LLC/SNAP header structure */
    361362typedef struct libtrace_llcsnap
    362363{
    … …  
    373374typedef struct libtrace_ether
    374375{
    375   uint8_t ether_dhost[6];       /**< destination ether addr */
    376   uint8_t ether_shost[6];       /**< source ether addr */
    377   uint16_t ether_type;          /**< packet type ID field (next-header) */
     376  uint8_t ether_dhost[6];       /**< Destination Ether Addr */
     377  uint8_t ether_shost[6];       /**< Source Ether Addr */
     378  uint16_t ether_type;          /**< Packet Type ID Field (next-header) */
    378379} PACKED libtrace_ether_t;
    379380
    … …  
    381382typedef struct libtrace_8021q
    382383{
    383   uint16_t vlan_pri:3;   /**< vlan user priority */
    384   uint16_t vlan_cfi:1;   /**< vlan format indicator,
     384  uint16_t vlan_pri:3;   /**< VLAN User Priority */
     385  uint16_t vlan_cfi:1;   /**< VLAN Format Indicator,
    385386                                   * 0 for ethernet, 1 for token ring */
    386   uint16_t vlan_id:12;   /**< vlan id */
    387   uint16_t vlan_ether_type;      /**< vlan sub-packet type ID field
     387  uint16_t vlan_id:12;   /**< VLAN Id */
     388  uint16_t vlan_ether_type;      /**< VLAN Sub-packet Type ID Field
    388389                                   * (next-header)*/
    389390} PACKED libtrace_8021q_t;
    … …  
    404405{
    405406 uint16_t header;
    406  uint16_t ether_type;           /**< ether type */
     407 uint16_t ether_type;           /**< Ether Type */
    407408} PACKED libtrace_pos_t;
    408409
    … …  
    442443DLLEXPORT void trace_help();
    443444
    444 /** Gets the output format for a given output trace
    445  *
    446  * @param libtrace      the output trace to get the name of the format fo
    447  * @return callee-owned null-terminated char* containing the output format
    448  *
    449  */
    450 DLLEXPORT SIMPLE_FUNCTION
    451 char *trace_get_output_format(const libtrace_out_t *libtrace);
    452 
    453445/** @name Trace management
    454446 * These members deal with creating, configuring, starting, pausing and
    … …  
    460452 *
    461453 * @param uri containing a valid libtrace URI
    462  * @return opaque pointer to a libtrace_t
     454 * @return an opaque pointer to a libtrace_t
    463455 *
    464456 * Valid URI's are:
    465457 *  - erf:/path/to/erf/file
    466  *  - erf:/path/to/erf/file.gz
    467  *  - erf:/path/to/rtclient/socket
    468458 *  - erf:-  (stdin)
    469459 *  - dag:/dev/dagcard                 
    … …  
    471461 *  - pcap:/path/to/pcap/file
    472462 *  - pcap:-
    473  *  - rtclient:hostname
    474  *  - rtclient:hostname:port
    475  *  - wag:-
    476  *  - wag:/path/to/wag/file
    477  *  - wag:/path/to/wag/file.gz
    478  *  - wag:/path/to/wag/socket
     463 *  - rt:hostname
     464 *  - rt:hostname:port
     465 *  - rtclient:hostname (deprecated)
     466 *  - rtclient:hostname:port (deprecated)
     467 *  - wag:/dev/wagcard
     468 *  - wtf:-
     469 *  - wtf:/path/to/wtf/file
    479470 *
    480471 *  If an error occured when attempting to open the trace file, an error
    … …  
    487478/** Creates a "dummy" trace file that has only the format type set.
    488479 *
    489  * @return opaque pointer to a (sparsely initialised) libtrace_t
     480 * @return an opaque pointer to a (sparsely initialised) libtrace_t
    490481 *
    491482 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions
    … …  
    498489 *
    499490 * @param uri   the uri string describing the output format and destination
    500  * @return opaque pointer to a libtrace_output_t
    501  * @author Shane Alcock
     491 * @return an opaque pointer to a libtrace_output_t
    502492 *
    503493 * Valid URI's are:
    504  *  - gzerf:/path/to/erf/file.gz
    505  *  - gzerf:/path/to/erf/file
    506  *  - rtserver:hostname
    507  *  - rtserver:hostname:port
     494 *  - erf:/path/to/erf/file
     495 *  - pcap:/path/to/pcap/file
     496 *  - wtf:/path/to/wtf/file
    508497 *
    509498 *  If an error occured when attempting to open the output trace, NULL is returned
    … …  
    514503/** Start the capture
    515504 * @param libtrace      The trace to start
    516  * @return 0 on success
     505 * @return 0 on success, -1 on failure
    517506 *
    518507 * This does the actual work with starting the trace capture, and applying
    … …  
    523512/** Pause the capture
    524513 * @param libtrace      The trace to pause
    525  * @return 0 on success
     514 * @return 0 on success, -1 on failure
    526515 *
    527516 * This stops a capture in progress and returns you to the configuration
    … …  
    533522/** Start an output trace
    534523 * @param libtrace      The trace to start
    535  * @return 0 on success
     524 * @return 0 on success, -1 on failure
    536525 *
    537526 * This does the actual work with starting a trace for write.  This generally
    … …  
    591580/** Close a trace output file, freeing up any resources it may have been using
    592581 * @param trace         the output trace file to be destroyed
    593  *
    594  * @author Shane Alcock
    595582 */
    596583DLLEXPORT void trace_destroy_output(libtrace_out_t *trace);
    … …  
    672659
    673660
    674 /** Read one packet from the trace into buffer
     661/** Read one packet from the trace
    675662 *
    676663 * @param trace         the libtrace opaque pointer
    … …  
    697684} libtrace_event_t;
    698685
    699 /** structure returned by libtrace_event explaining what the current event is */
     686/** Structure returned by libtrace_event explaining what the current event is */
    700687typedef struct libtrace_eventobj_t {
    701688        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
    … …  
    708695} libtrace_eventobj_t;
    709696
    710 /** process a libtrace event
     697/** Processes the next libtrace event
    711698 * @param trace the libtrace opaque pointer
    712699 * @param packet the libtrace_packet opaque pointer
    … …  
    744731 * @return a pointer to the link layer, or NULL if there is no link layer
    745732 *
    746  * @note you should call getLinkType() to find out what type of link layer
    747  * this is
     733 * @note you should call trace_get_link_type to find out what type of link
     734 * layer this is
    748735 */
    749736DLLEXPORT SIMPLE_FUNCTION
    … …  
    753740 * @param packet        the packet opaque pointer
    754741 *
    755  * @return a pointer to the IP header, or NULL if there is not an IP packet
     742 * @return a pointer to the IP header, or NULL if there is no IP header
    756743 */
    757744DLLEXPORT SIMPLE_FUNCTION
    … …  
    831818 * @note This is similar to trace_get_payload_from_icmp in libtrace2
    832819 */
    833 DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp, uint32_t *skipped);
     820DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp, uint32_t *remaining);
    834821
    835822/** get a pointer to the TCP header (if any)
    … …  
    975962 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
    976963 * past 1970-01-01, the lower 32bits are partial seconds)
    977  * @author Daniel Lawson
    978964 */
    979965DLLEXPORT SIMPLE_FUNCTION
    … …  
    984970 *
    985971 * @return time that this packet was seen in a struct timeval
    986  * @author Daniel Lawson
    987  * @author Perry Lorier
    988972 */
    989973DLLEXPORT SIMPLE_FUNCTION
    … …  
    994978 *
    995979 * @return time that this packet was seen in 64bit floating point seconds
    996  * @author Daniel Lawson
    997  * @author Perry Lorier
    998980 */
    999981DLLEXPORT SIMPLE_FUNCTION
    … …  
    10431025 * @param packet        the packet opaque pointer
    10441026 * @return the size of the packet in the trace
    1045  * @author Perry Lorier
    10461027 * @note Due to this being a header capture, or anonymisation, this may not
    10471028 * be the same size as the original packet.  See get_wire_length() for the
    … …  
    10501031 * @note This is sometimes called the "snaplen".
    10511032 * @note The return size refers to the network-level payload of the packet and
    1052  * does not include any capture headers. For example, an Ethernet packet with
    1053  * an empty TCP packet will return sizeof(ethernet_header) + sizeof(ip_header)
    1054  * + sizeof(tcp_header).
     1033 * does not include any capture framing headers. For example, an Ethernet
     1034 * packet with an empty TCP packet will return sizeof(ethernet_header) +
     1035 * sizeof(ip_header) + sizeof(tcp_header).
    10551036 */
    10561037DLLEXPORT SIMPLE_FUNCTION
    … …  
    10701051 * @param packet        the packet opaque pointer
    10711052 * @return the size of the packet as it was on the wire.
    1072  * @author Perry Lorier
    1073  * @author Daniel Lawson
    10741053 * @note this length corresponds to the difference between the size of a
    10751054 * captured packet in memory, and the captured length of the packet
    … …  
    10921071 * @param packet        the packet opaque pointer
    10931072 * @return libtrace_linktype_t
    1094  * @author Perry Lorier
    1095  * @author Daniel Lawson
    10961073 */
    10971074DLLEXPORT SIMPLE_FUNCTION
    … …  
    11121089 * Other values are possible, which might be overloaded to mean special things
    11131090 * for a special trace.
    1114  * @author Daniel Lawson
    11151091 */
    11161092DLLEXPORT SIMPLE_FUNCTION
    … …  
    11241100 * @param filterstring a char * containing the bpf filter string
    11251101 * @return opaque pointer pointer to a libtrace_filter_t object
    1126  * @author Daniel Lawson
    11271102 * @note The filter is not actually compiled at this point, so no correctness
    11281103 * tests are performed here. trace_bpf_setfilter will always return ok, but
    … …  
    12001175/** Get the source port
    12011176 * @param packet        the packet to read from
    1202  * @return a port in \em HOST byte order, or equivilent to ports for this
     1177 * @return a port in \em HOST byte order, or equivalent to ports for this
    12031178 * protocol, or 0 if this protocol has no ports.
    1204  * @author Perry Lorier
    12051179 */
    12061180DLLEXPORT SIMPLE_FUNCTION
    … …  
    12111185 * @return a port in \em HOST byte order, or equivilent to ports for this
    12121186 * protocol, or 0 if this protocol has no ports.
    1213  * @author Perry Lorier
    12141187 */
    12151188DLLEXPORT SIMPLE_FUNCTION
    … …  
    12221195 * @return one of USE_SOURCE or USE_DEST depending on which one you should use
    12231196 * @note ports must be in \em HOST byte order!
    1224  * @author Daniel Lawson
    12251197 */
    12261198DLLEXPORT SIMPLE_FUNCTION
    … …  
    12281200
    12291201/** Takes a uri and splits it into a format and uridata component.
    1230  * Primarily for internal use but made available for external use.
    12311202 * @param uri           the uri to be parsed
    12321203 * @param format        destination location for the format component of the uri
    12331204 * @return 0 if an error occured, otherwise return the uridata component
    1234  * @author Shane Alcock
    12351205 */
    12361206DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
    … …  
    12511221};
    12521222
    1253 /** Gets the framing header type for a given packet.
     1223/** Gets the format type for a given packet.
    12541224 * @param packet        the packet opaque pointer
    12551225 * @return the format of the packet
    … …  
    12571227DLLEXPORT
    12581228enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
     1229
    12591230
    12601231#ifdef __cplusplus

  • lib/trace.c

    r4e65f42 r83445f0  
    252252#define URI_PROTO_LINE 16
    253253
    254 /* Gets the name of the output format for a given output trace.
    255  *
    256  * @params libtrace     the output trace to get the name of the format for
    257  * @returns callee-owned null-terminated char* containing the output format
    258  *
    259  */
    260 DLLEXPORT SIMPLE_FUNCTION
    261 char *trace_get_output_format(const libtrace_out_t *libtrace) {
    262         char * format = libtrace->format->name;
    263 
    264         return format;
    265 }
    266 
    267254
    268255/* Create a trace file from a URI
Note: See TracChangeset for help on using the changeset viewer.