Changeset fba4ca0 for lib/trace.c


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/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.