Changeset 91c9552 for lib/libtrace.h


Ignore:
Timestamp:
02/23/06 11:21:19 (16 years ago)
Author:
Perry Lorier <perry@…>
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:
aa62105
Parents:
c2d5f23
Message:

Documentation fixes
Make bpf return valid errors
Add trace_copy_packet()

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace.h

    rc1db742 r91c9552  
    118118};
    119119
    120 /** @name Packet structures
     120/** @name Protocol structures
    121121 * These convenience structures are here as they are portable ways of dealing
    122122 * with various protocols.
     
    290290char *trace_get_output_format(const libtrace_out_t *libtrace);
    291291
    292 /** @name Creation and destruction of traces
    293  * These members deal with creating, configuring and cleaning up a trace object
     292/** @name Trace management
     293 * These members deal with creating, configuring, starting, pausing and
     294 * cleaning up a trace object
    294295 *@{
    295296 */
     
    449450libtrace_packet_t *trace_create_packet();
    450451
     452/** Copy a packet
     453 * @param packet        the source packet to copy
     454 * @return a new packet which has the same content as the source packet
     455 * @note This always involves a copy, which can be slow.  Use of this
     456 * function should be avoided where possible.
     457 * @par The reason you would want to use this function is that a zerocopied
     458 * packet from a device is using the devices memory which may be a limited
     459 * resource.  Copying the packet will cause it to be copied into the systems
     460 * memory.
     461 */
     462libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet);
     463
    451464/** Destroy a packet object
    452465 *
     
    510523/*@}*/
    511524
    512 /** @name Headers
    513  * These functions locate and return a pointer to various headers inside a packet
     525/** @name Protocol decodes
     526 * These functions locate and return a pointer to various headers inside a
     527 * packet
    514528 * @{
    515529 */
     
    669683SIMPLE_FUNCTION
    670684double trace_get_seconds(const libtrace_packet_t *packet);
    671 /*@}*/
    672 
    673 /** @name Sizes
    674  * This section deals with finding or setting the various different lengths
    675  * a packet can have
    676  * @{
    677  */
    678 /** Get the size of the packet in the trace
    679  * @param packet        the packet opaque pointer
    680  * @return the size of the packet in the trace
    681  * @author Perry Lorier
    682  * @note Due to this being a header capture, or anonymisation, this may not
    683  * be the same size as the original packet.  See get_wire_length() for the original
    684  * size of the packet.
    685  * @note This can (and often is) different for different packets in a trace!
    686  * @par
    687  *  This is sometimes called the "snaplen".
    688  */
    689 SIMPLE_FUNCTION
    690 int trace_get_capture_length(const libtrace_packet_t *packet);
    691 
    692 /** Get the size of the packet as it was seen on the wire.
    693  * @param packet        the packet opaque pointer
    694  * @return the size of the packet as it was on the wire.
    695  * @author Perry Lorier
    696  * @author Daniel Lawson
    697  * @note Due to the trace being a header capture, or anonymisation this may
    698  * not be the same as the Capture Len.
    699  */
    700 SIMPLE_FUNCTION
    701 int trace_get_wire_length(const libtrace_packet_t *packet);
    702 
    703 /** Get the length of the capture framing headers.
    704  * @param packet        the packet opaque pointer
    705  * @return the size of the packet as it was on the wire.
    706  * @author Perry Lorier
    707  * @author Daniel Lawson
    708  * @note this length corresponds to the difference between the size of a
    709  * captured packet in memory, and the captured length of the packet
    710  */
    711 SIMPLE_FUNCTION
    712 int trace_get_framing_length(const libtrace_packet_t *packet);
    713 
    714 /** Truncate the packet at the suggested length
    715  * @param packet        the packet opaque pointer
    716  * @param size          the new length of the packet
    717  * @return the new length of the packet, or the original length of the
    718  * packet if unchanged
    719  * @author Daniel Lawson
    720  */
    721 size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
    722685
    723686/** Seek within a trace
     
    742705 */
    743706int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
     707
     708/*@}*/
     709
     710/** @name Sizes
     711 * This section deals with finding or setting the various different lengths
     712 * a packet can have
     713 * @{
     714 */
     715/** Get the size of the packet in the trace
     716 * @param packet        the packet opaque pointer
     717 * @return the size of the packet in the trace
     718 * @author Perry Lorier
     719 * @note Due to this being a header capture, or anonymisation, this may not
     720 * be the same size as the original packet.  See get_wire_length() for the original
     721 * size of the packet.
     722 * @note This can (and often is) different for different packets in a trace!
     723 * @par
     724 *  This is sometimes called the "snaplen".
     725 */
     726SIMPLE_FUNCTION
     727int trace_get_capture_length(const libtrace_packet_t *packet);
     728
     729/** Get the size of the packet as it was seen on the wire.
     730 * @param packet        the packet opaque pointer
     731 * @return the size of the packet as it was on the wire.
     732 * @author Perry Lorier
     733 * @author Daniel Lawson
     734 * @note Due to the trace being a header capture, or anonymisation this may
     735 * not be the same as the Capture Len.
     736 */
     737SIMPLE_FUNCTION
     738int trace_get_wire_length(const libtrace_packet_t *packet);
     739
     740/** Get the length of the capture framing headers.
     741 * @param packet        the packet opaque pointer
     742 * @return the size of the packet as it was on the wire.
     743 * @author Perry Lorier
     744 * @author Daniel Lawson
     745 * @note this length corresponds to the difference between the size of a
     746 * captured packet in memory, and the captured length of the packet
     747 */
     748SIMPLE_FUNCTION
     749int trace_get_framing_length(const libtrace_packet_t *packet);
     750
     751/** Truncate ("snap") the packet at the suggested length
     752 * @param packet        the packet opaque pointer
     753 * @param size          the new length of the packet
     754 * @return the new length of the packet, or the original length of the
     755 * packet if unchanged
     756 * @author Daniel Lawson
     757 */
     758size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
    744759
    745760/*@}*/
     
    830845 * @param filter        the filter opaque pointer
    831846 * @param packet        the packet opaque pointer
    832  * @return 0 if the filter fails, 1 if it succeeds
    833  * @author Daniel Lawson
    834  * @note Due to the way BPF filters are built, the filter is not actually compiled
    835  * 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.
     847 * @return 1 if the filter matches, 0 if it doesn't.
     848 * @note Due to the way BPF filters are built, the filter is not actually
     849 * compiled until the first time trace_bpf_filter is called. If your filter is
     850 * incorrect, it will generate an error message and assert, exiting the
     851 * program. This behaviour may change to more graceful handling of this error
     852 * in the future.
    836853 */
    837854int trace_bpf_filter(libtrace_filter_t *filter,
Note: See TracChangeset for help on using the changeset viewer.