Changeset fba4ca0 for lib


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

Location:
lib
Files:
3 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 */

  • lib/libtrace_int.h

    rda17570 rfba4ca0  
    7979} trace_err;
    8080
     81/** Opaque structure holding information about a packet */
     82#define LIBTRACE_PACKET_BUFSIZE 65536
     83struct libtrace_packet_t {
     84        struct libtrace_t *trace;
     85        //void *buffer;
     86        char buffer[LIBTRACE_PACKET_BUFSIZE];
     87        size_t size;
     88        uint8_t status;
     89};
    8190
    8291#define RP_BUFSIZE 65536

  • lib/trace.c

    r5bbe424 rfba4ca0  
    3030
    3131
    32 /** @file
     32/* @file
    3333 *
    3434 * @brief Trace file processing library
    … …  
    120120
    121121#if HAVE_BPF
    122 /** A type encapsulating a bpf filter
     122/* A type encapsulating a bpf filter
    123123 * This type covers the compiled bpf filter, as well as the original filter
    124124 * string
    … …  
    151151}
    152152
    153 /** Prints help information for libtrace
     153/* Prints help information for libtrace
    154154 *
    155155 * Function prints out some basic help information regarding libtrace,
    … …  
    166166}
    167167
     168/* Prints error information
     169 *
     170 * Prints out a descriptive error message for the currently set trace_err value
     171 */
    168172void trace_perror(char *caller) {
    169173        switch (trace_err.err_num) {
    … …  
    196200#define URI_PROTO_LINE 16
    197201
    198 /** Gets the name of the output format for a given output trace.
     202/* Gets the name of the output format for a given output trace.
    199203 *
    200204 * @params libtrace     the output trace to get the name of the format for
    201  * @returns the output format
     205 * @returns callee-owned null-terminated char* containing the output format
    202206 *
    203207 */
    … …  
    208212}
    209213
    210 /** Create a trace file from a URI
    211  *
     214/* Create a trace file from a URI
     215 *
     216 * @params char * containing a valid libtrace URI
    212217 * @returns opaque pointer to a libtrace_t
    213218 *
    … …  
    217222 *  erf:/path/to/rtclient/socket
    218223 *  erf:-                       (stdin)
     224 *  dag:/dev/dagcard
    219225 *  pcapint:pcapinterface               (eg: pcapint:eth0)
    220226 *  pcap:/path/to/pcap/file
    … …  
    226232 *  wag:/path/to/wag/file.gz
    227233 *  wag:/path/to/wag/socket
    228  *  wagint:/dev/device
    229  *
    230  * URIs which have yet to be implemented are:
    231  * dag:/dev/dagcard
    232  * pcap:/path/to/pcap/socket
    233234 *
    234235 * If an error occured when attempting to open a trace, NULL is returned
    … …  
    293294}
    294295
     296/* Creates a "dummy" trace file that has only the format type set.
     297 *
     298 * @returns opaque pointer to a (sparsely initialised) libtrace_t
     299 *
     300 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
     301 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
     302 * that are not associated with a libtrace_t structure.
     303 */
    295304struct libtrace_t * trace_create_dead (char *uri) {
    296305        struct libtrace_t *libtrace = malloc(sizeof(struct libtrace_t));
    … …  
    327336
    328337}
    329        
    330 /** Creates a libtrace_out_t structure and the socket / file through which output will be directed.
    331  *
    332  * @param uri   the uri string describing the output format and the destination
    333  * @returns the newly created libtrace_out_t structure
    334  *
     338
     339/** Creates a trace output file from a URI.
     340 *
     341 * @param uri   the uri string describing the output format and destination
     342 * @returns opaque pointer to a libtrace_output_t
    335343 * @author Shane Alcock
    336  * */
     344 *
     345 * Valid URI's are:
     346 *  - gzerf:/path/to/erf/file.gz
     347 *  - gzerf:/path/to/erf/file
     348 *  - rtserver:hostname
     349 *  - rtserver:hostname:port
     350 *
     351 *  If an error occured when attempting to open the output trace, NULL is returned
     352 *  and trace_errno is set. Use trace_perror() to get more information
     353 */
     354       
    337355struct libtrace_out_t *trace_output_create(char *uri) {
    338356        struct libtrace_out_t *libtrace = malloc(sizeof(struct libtrace_out_t));
    … …  
    388406}
    389407
    390 /** Parses an output options string and calls the appropriate function to deal with output options.
     408/* Parses an output options string and calls the appropriate function to deal with output options.
    391409 *
    392410 * @param libtrace      the output trace object to apply the options to
    … …  
    415433}
    416434
    417 /** Close a trace file, freeing up any resources it may have been using
     435/* Close a trace file, freeing up any resources it may have been using
    418436 *
    419437 */
    … …  
    432450        free(libtrace);
    433451}
    434 /** Close an output trace file, freeing up any resources it may have been using
     452/* Close an output trace file, freeing up any resources it may have been using
    435453 *
    436454 * @param libtrace      the output trace file to be destroyed
    … …  
    446464}
    447465
    448 /** Read one packet from the trace into buffer
     466/* Read one packet from the trace into buffer
    449467 *
    450468 * @param libtrace      the libtrace opaque pointer
    451469 * @param packet        the packet opaque pointer
    452  * @returns false if it failed to read a packet
     470 * @returns 0 on EOF, negative value on error
    453471 *
    454472 */
    … …  
    470488}
    471489
    472 /** Writes a packet to the specified output
     490/* Writes a packet to the specified output
    473491 *
    474492 * @param libtrace      describes the output format, destination, etc.
    … …  
    488506}
    489507
    490 /** get a pointer to the link layer
     508/* get a pointer to the link layer
    491509 * @param packet        a pointer to a libtrace_packet structure
    492510 *
    493511 * @returns a pointer to the link layer, or NULL if there is no link layer
    494  * you should call trace_get_link_type() to find out what type of link layer this is
     512 *
     513 * @note you should call trace_get_link_type() to find out what type of link layer this is
    495514 */
    496515void *trace_get_link(const struct libtrace_packet_t *packet) {
    … …  
    503522}
    504523
    505 /** get a pointer to the IP header (if any)
     524/* get a pointer to the IP header (if any)
    506525 * @param packet        a pointer to a libtrace_packet structure
    507526 *
    … …  
    542561                case TRACE_TYPE_ETH:
    543562                        {
    544                                 struct ether_header *eth =
     563                                struct libtrace_ether *eth =
    545564                                        trace_get_link(packet);
    546565                                if (!eth) {
    … …  
    622641#define SW_IP_OFFMASK 0xff1f
    623642
    624 /** get a pointer to the TCP header (if any)
     643/* get a pointer to the TCP header (if any)
    625644 * @param packet        a pointer to a libtrace_packet structure
    626645 *
    … …  
    640659}
    641660
    642 /** get a pointer to the TCP header (if any) given a pointer to the IP header
     661/* get a pointer to the TCP header (if any) given a pointer to the IP header
    643662 * @param ip            The IP header
    644663 * @param[out] skipped  An output variable of the number of bytes skipped
    … …  
    663682}
    664683
    665 /** get a pointer to the UDP header (if any)
     684/* get a pointer to the UDP header (if any)
    666685 * @param packet        a pointer to a libtrace_packet structure
    667686 *
    … …  
    682701}
    683702
    684 /** get a pointer to the UDP header (if any) given a pointer to the IP header
     703/* get a pointer to the UDP header (if any) given a pointer to the IP header
    685704 * @param ip            The IP header
    686705 * @param[out] skipped  An output variable of the number of bytes skipped
    … …  
    705724
    706725
    707 /** get a pointer to the ICMP header (if any)
     726/* get a pointer to the ICMP header (if any)
    708727 * @param packet        a pointer to a libtrace_packet structure
    709728 *
    … …  
    723742}
    724743
    725 /** get a pointer to the ICMP header (if any) given a pointer to the IP header
     744/* get a pointer to the ICMP header (if any) given a pointer to the IP header
    726745 * @param ip            The IP header
    727746 * @param[out] skipped  An output variable of the number of bytes skipped
    … …  
    744763        return icmpptr;
    745764}
    746 /** parse an ip or tcp option
     765/* parse an ip or tcp option
    747766 * @param[in,out] ptr   the pointer to the current option
    748767 * @param[in,out] len   the length of the remaining buffer
    … …  
    793812
    794813
    795 /** Get the current time in DAG time format
     814/* Get the current time in DAG time format
    796815 * @param packet        a pointer to a libtrace_packet structure
    797816 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
    … …  
    821840}
    822841
    823 /** Get the current time in struct timeval
     842/* Get the current time in struct timeval
    824843 * @param packet        a pointer to a libtrace_packet structure
    825844 *
    … …  
    862881}
    863882
    864 /** Get the current time in floating point seconds
     883/* Get the current time in floating point seconds
    865884 * @param packet        a pointer to a libtrace_packet structure
    866885 * @returns time that this packet was seen in 64bit floating point seconds
    … …  
    888907}
    889908
    890 /** Get the size of the packet in the trace
     909/* Get the size of the packet in the trace
    891910 * @param packet the packet opaque pointer
    892911 * @returns the size of the packet in the trace
    … …  
    907926}
    908927       
    909 /** Get the size of the packet as it was seen on the wire.
     928/* Get the size of the packet as it was seen on the wire.
    910929 * @param packet        a pointer to a libtrace_packet structure
    911930 *
    … …  
    924943}
    925944
    926 /** Get the type of the link layer
     945/* Get the type of the link layer
    927946 * @param packet        a pointer to a libtrace_packet structure
    928947 * @returns libtrace_linktype_t
    … …  
    937956}
    938957
    939 /** Get the source MAC addres
     958/* Get the source MAC addres
    940959 * @param packet        a pointer to a libtrace_packet structure
    941960 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
    … …  
    945964        void *link = trace_get_link(packet);
    946965        struct ieee_802_11_header *wifi = link;
    947         struct ether_header *ethptr = link;
     966        struct libtrace_ether *ethptr = link;
    948967        if (!link)
    949968                return NULL;
    … …  
    959978}
    960979
    961 /** Get the destination MAC addres
     980/* Get the destination MAC addres
    962981 * @param packet a libtrace_packet pointer
    963982 * @returns a pointer to the destination mac, (or NULL if there is no
    … …  
    968987        void *link = trace_get_link(packet);
    969988        struct ieee_802_11_header *wifi = link;
    970         struct ether_header *ethptr = link;
     989        struct libtrace_ether *ethptr = link;
    971990        if (!link)
    972991                return NULL;
    … …  
    9831002
    9841003
    985 /** process a libtrace event
     1004/* process a libtrace event
    9861005 * @param trace the libtrace opaque pointer
    9871006 * @param packet the libtrace_packet opaque pointer
    … …  
    10171036}
    10181037
    1019 /** setup a BPF filter
     1038/* setup a BPF filter
    10201039 * @param filterstring a char * containing the bpf filter string
    10211040 * @returns opaque pointer pointer to a libtrace_filter_t object
    … …  
    10341053}
    10351054
    1036 /** apply a BPF filter
     1055/* apply a BPF filter
    10371056 * @param filter the filter opaque pointer
    10381057 * @param packet the packet opaque pointer
    … …  
    10961115}
    10971116
    1098 /** Set the direction flag, if it has one
     1117/* Set the direction flag, if it has one
    10991118 * @param packet the packet opaque pointer
    11001119 * @param direction the new direction (0,1,2,3)
    … …  
    11101129}
    11111130
    1112 /** Get the direction flag, if it has one
     1131/* Get the direction flag, if it has one
    11131132 * @param packet a pointer to a libtrace_packet structure
    11141133 * @returns a signed value containing the direction flag, or -1 if this is not supported
    … …  
    11461165        port = (struct ports_t *)((ptrdiff_t)ip + (ip->ip_hl * 4));
    11471166
    1148         return htons(port->src);
     1167        return ntohs(port->src);
    11491168}
    11501169
    … …  
    11641183        port = (struct ports_t *)((ptrdiff_t)ip + (ip->ip_hl * 4));
    11651184
    1166         return htons(port->dst);
     1185        return ntohs(port->dst);
    11671186}
    11681187
    … …  
    12821301}
    12831302
    1284 /** Truncate the packet at the suggested length
     1303/* Truncate the packet at the suggested length
    12851304 * @param packet        the packet opaque pointer
    12861305 * @param size          the new length of the packet
Note: See TracChangeset for help on using the changeset viewer.