Changeset fba4ca0 for lib/libtrace.h


Ignore:
Timestamp:
09/13/05 11:06:34 (16 years ago)
Author:
Daniel Lawson <dlawson@…>
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:
1e66c64
Parents:
d3e4697
Message:

documentation cleanups, moved libtrace_packet_t definition into libtrace_int.h

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace.h

    r5bbe424 rfba4ca0  
    3636
    3737/** API version as 3 byte hex digits, eg 0xXXYYZZ */
    38 #define LIBTRACE_API_VERSION 0x100014
     38#define LIBTRACE_API_VERSION 0x100015
    3939
    4040#ifdef __cplusplus
     
    5555 *
    5656 * @par Usage
    57  * <ol>
    58  * <li> include "libtrace.h"
    59  * <li> call create_trace with the uri of the trace you're interested in.<br>
    60  * This is usually passed in as argv[1] to your program.
    61  * <li> call libtrace_read_packet(), passing in the libtrace_t returned from
    62  * create trace and a buffer (and the buffer length)
    63  * <li> call getIP() on the buffer, and do whatever you need
    64  * <li> loop back to step 3, until libtrace_read_packet() returns -1
    65  * </ol>
     57 * See the example/ directory in the source distribution for some simple examples
    6658 * @par Linking
    6759 * To use this library you need to link against libtrace by passing -ltrace
     
    8678
    8779/** Opaque structure holding information about a packet */
    88 #define LIBTRACE_PACKET_BUFSIZE 65536
    89 struct libtrace_packet_t {
    90         struct libtrace_t *trace;
    91         //void *buffer;
    92         char buffer[LIBTRACE_PACKET_BUFSIZE];
    93         size_t size;
    94         uint8_t status;
    95 };
     80struct libtrace_packet_t;
    9681
    9782/** Enumeration of error codes */
     
    10085/** Structure for dealing with IP packets */
    10186struct libtrace_ip
    102   {
     87{
    10388#if BYTE_ORDER == LITTLE_ENDIAN
    10489    unsigned int ip_hl:4;               /**< header length */
     
    123108    struct in_addr ip_src;              /**< source address */
    124109    struct in_addr ip_dst;              /**< dest address */
    125   };
     110} __attribute__ ((__packed__));
    126111
    127112/** Structure for dealing with TCP packets */
     
    158143    u_int16_t check;            /**< Checksum */
    159144    u_int16_t urg_ptr;          /**< Urgent Pointer */
    160 };
     145} __attribute__ ((__packed__));
    161146
    162147/** UDP Header for dealing with UDP packets */
     
    166151  u_int16_t     len;            /**< Length */
    167152  u_int16_t     check;          /**< Checksum */
    168 };
     153} __attribute__ ((__packed__));
    169154
    170155/** ICMP Header for dealing with icmp packets */
     
    188173    } frag;                     /**< path mtu discovery */
    189174  } un;
    190 };
     175} __attribute__ ((__packed__));
     176
     177/** 802.3 frame */
     178struct libtrace_ether
     179{
     180  u_int8_t ether_dhost[6];      /* destination ether addr */
     181  u_int8_t ether_shost[6];      /* source ether addr */
     182  u_int16_t ether_type;         /* packet type ID field (next-header) */
     183} __attribute__ ((__packed__));
    191184
    192185/** 802.1Q frame */
     
    195188  u_int8_t  ether_dhost[6];      /* destination eth addr */
    196189  u_int8_t  ether_shost[6];      /* source ether addr    */
    197   u_int16_t ether_type;                 /* packet type ID field , 0x8100 for VLAN */
    198   u_int16_t vlan_pri:3;                 /* vlan user priority */
    199   u_int16_t vlan_cfi:1;                 /* vlan format indicator, 0 for ethernet, 1 for token ring */
    200   u_int16_t vlan_id:12;                 /* vlan id */
    201   u_int16_t vlan_ether_type;            /* vlan sub-packet type ID field (next-header)*/
     190  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
     191  u_int16_t vlan_pri:3;          /* vlan user priority */
     192  u_int16_t vlan_cfi:1;          /* vlan format indicator, 0 for ethernet, 1 for token ring */
     193  u_int16_t vlan_id:12;          /* vlan id */
     194  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
    202195} __attribute__ ((__packed__));
    203196
     
    211204/** Gets the output format for a given output trace
    212205 *
     206 * @params libtrace     the output trace to get the name of the format fo
     207 * @returns callee-owned null-terminated char* containing the output format
     208 *
    213209 */
    214210char *trace_get_output_format(struct libtrace_out_t *libtrace);
     
    222218/** Create a trace file from a URI
    223219 *
     220 * @params char * containing a valid libtrace URI
    224221 * @returns opaque pointer to a libtrace_t
    225222 *
     
    229226 *  - erf:/path/to/rtclient/socket
    230227 *  - erf:-  (stdin)
    231  *  - dag:/dev/dagcard                  (implementd?)
     228 *  - dag:/dev/dagcard                 
    232229 *  - pcapint:pcapinterface                (eg: pcap:eth0)
    233230 *  - pcap:/path/to/pcap/file
    234  *  - pcap:/path/to/pcap/file.gz
    235  *  - pcap:/path/to/pcap/socket         (implemented?)
    236231 *  - pcap:-
    237232 *  - rtclient:hostname
    238233 *  - rtclient:hostname:port
     234 *  - wag:-
    239235 *  - wag:/path/to/wag/file
    240236 *  - wag:/path/to/wag/file.gz
    241237 *  - wag:/path/to/wag/socket
    242  *  - wag:/dev/device
    243238 *
    244239 *  If an error occured when attempting to open the trace file, NULL is returned
    245  *  and an error is output to stdout.
     240 *  and trace_errno is set. Use trace_perror() to get more information
    246241 */
    247242struct libtrace_t *trace_create(char *uri);
     
    259254/** Creates a trace output file from a URI.
    260255 *
     256 * @param uri   the uri string describing the output format and destination
    261257 * @returns opaque pointer to a libtrace_output_t
     258 * @author Shane Alcock
    262259 *
    263260 * Valid URI's are:
     
    267264 *  - rtserver:hostname:port
    268265 *
    269  *  If an error occured when attempting to open the output trace, NULL is returned and
    270  *  an error is output to stdout.
     266 *  If an error occured when attempting to open the output trace, NULL is returned
     267 *  and trace_errno is set. Use trace_perror() to get more information
    271268 */
    272269struct libtrace_out_t *trace_output_create(char *uri);
    273270
    274 /** Configures a trace output file as specified by an option string in getopt() format
    275  *
    276  * @param libtrace      the output trace file to be configured
    277  * @param options       the string containing the configuration options
    278  * @returns -1 if configuration fails, 0 if successful
     271/* Parses an output options string and calls the appropriate function to deal with output options.
     272 *
     273 * @param libtrace      the output trace object to apply the options to
     274 * @param options       the options string
     275 * @returns -1 if option configuration failed, 0 otherwise
     276 *
     277 * @author Shane Alcock
    279278 */
    280279int trace_output_config(struct libtrace_out_t *libtrace, char *options);
     
    289288/** Close a trace output file, freeing up any resources it may have been using
    290289 *
     290 * @param libtrace      the output trace file to be destroyed
     291 *
     292 * @author Shane Alcock
    291293 */
    292294void trace_output_destroy(struct libtrace_out_t *trace);
     
    296298 * @param trace         the libtrace opaque pointer
    297299 * @param packet        the packet opaque pointer
    298  * @returns false if it failed to read a packet
     300 * @returns 0 on EOF, negative value on error
    299301 *
    300302 */
     
    424426 *
    425427 * @returns time that this packet was seen in 64bit floating point seconds
     428 * @author Daniel Lawson
    426429 * @author Perry Lorier
    427430 */
     
    537540 * @param trace the libtrace opaque pointer
    538541 * @param packet the libtrace_packet opaque pointer
    539  * @param fd a pointer to a file descriptor to listen on
    540  * @param seconds a pointer the time in seconds since to the next event
    541542 * @returns libtrace_event struct containing the type, and potential
    542543 *      fd or seconds to sleep on
     
    555556 * @returns opaque pointer pointer to a libtrace_filter_t object
    556557 * @author Daniel Lawson
     558 * @note The filter is not actually compiled at this point, so no correctness
     559 * tests are performed here. trace_bpf_setfilter will always return ok, but
     560 * if the filter is poorly constructed an error will be generated when the
     561 * filter is actually used
    557562 */
    558563struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
     
    563568 * @returns 0 if the filter fails, 1 if it succeeds
    564569 * @author Daniel Lawson
     570 * @note Due to the way BPF filters are built, the filter is not actually compiled
     571 * until the first time trace_bpf_filter is called. If your filter is incorrect, it will generate an error message and assert, exiting the program. This behaviour may change to more graceful handling of this error in the future.
    565572 */
    566573int trace_bpf_filter(struct libtrace_filter_t *filter,
     
    591598 * @param dest          the destination port from the packet
    592599 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
    593  * @note ports must be in \em host byte order!
     600 * @note ports must be in \em HOST byte order!
    594601 * @author Daniel Lawson
    595602 */
Note: See TracChangeset for help on using the changeset viewer.