Changeset 042f345
- Timestamp:
- 01/22/10 17:03:08 (11 years ago)
- 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:
- fc710bf
- Parents:
- f68d5b8
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
lib/libtrace.h.in
rb7a328d r042f345 2 2 * This file is part of libtrace 3 3 * 4 * Copyright (c) 2007,2008 The University of Waikato, Hamilton, New Zealand. 4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton, 5 * New Zealand. 6 * 5 7 * Authors: Daniel Lawson 6 8 * Perry Lorier … … 42 44 * 43 45 * This library provides a per packet interface into a trace file, or a live 44 * captures. It supports ERF, DAG cards, WAG cards, WAG's event format,45 * pcapetc.46 * captures. It supports ERF, DAG cards, PCAP, Linux and BSD native sockets, 47 * legacy ERF formats etc. 46 48 * 47 49 * @par Usage 48 * See the example/ directory in the source distribution for some simple examples 50 * See the example/ directory in the source distribution for some simple 51 * examples 52 * 49 53 * @par Linking 50 54 * To use this library you need to link against libtrace by passing -ltrace … … 138 142 ((@LIBTRACE_MAJOR@<<16)|(@LIBTRACE_MID@<<8)|(@LIBTRACE_MINOR@)) 139 143 144 /** Replaced with the current SVN revision number when 'make dist' is invoked 145 * to create a distributable tarball */ 140 146 #define LIBTRACE_SVN_REVISION 0 147 148 /** DAG driver version installed on the current system */ 141 149 #define DAG_DRIVER_V "@DAG_VERSION_NUM@" 142 150 … … 171 179 typedef struct libtrace_filter_t libtrace_filter_t; 172 180 173 /** If a packet has memory allocated174 * If the packet has allocated it's own memory it's buffer_control should175 * be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be176 * free()'d. If it's doing zerocopy out of memory owned by something else177 * it should be TRACE_CTRL_EXTERNAL.178 * @note the letters p and e are magic numbers used to detect if the packet179 * wasn't created properly 181 /** If the packet has allocated its own memory the buffer_control should be 182 * set to TRACE_CTRL_PACKET, so that the memory will be freed when the packet 183 * is destroyed. If the packet has been zerocopied out of memory owned by 184 * something else, e.g. a DAG card, it should be TRACE_CTRL_EXTERNAL. 185 * 186 * @note The letters p and e are magic numbers used to detect if the packet 187 * wasn't created properly. 180 188 */ 181 189 typedef enum { 182 TRACE_CTRL_PACKET='p', 183 TRACE_CTRL_EXTERNAL='e' 190 TRACE_CTRL_PACKET='p', /**< Buffer memory is owned by the packet */ 191 TRACE_CTRL_EXTERNAL='e' /**< Buffer memory is owned by an external source */ 184 192 } buf_control_t; 193 185 194 /** The size of a packet's buffer when managed by libtrace */ 186 195 #define LIBTRACE_PACKET_BUFSIZE 65536 187 196 188 /** libtrace error information */197 /** Libtrace error information */ 189 198 typedef struct trace_err_t{ 190 199 int err_num; /**< error code */ … … 214 223 }; 215 224 216 /** Enumeration of DLT supported by libtrace225 /** Enumeration of DLTs supported by libtrace 217 226 */ 218 227 typedef enum { … … 221 230 TRACE_DLT_PPP = 9, 222 231 TRACE_DLT_ATM_RFC1483 = 11, 232 223 233 /* Sigh. This is handled in files with LINKTYPE's */ 224 234 #ifdef __OpenBSD__ … … 239 249 typedef enum { 240 250 /* TRACE_TYPE_LEGACY = 0 Obsolete */ 241 TRACE_TYPE_HDLC_POS = 1, 251 TRACE_TYPE_HDLC_POS = 1, /**< HDLC over POS */ 242 252 TRACE_TYPE_ETH = 2, /**< 802.3 style Ethernet */ 243 253 TRACE_TYPE_ATM = 3, /**< ATM frame */ … … 245 255 TRACE_TYPE_NONE = 5, /**< Raw IP frames */ 246 256 TRACE_TYPE_LINUX_SLL = 6, /**< Linux "null" framing */ 247 TRACE_TYPE_PFLOG = 7, /**< FreeBSD's PFl ug */257 TRACE_TYPE_PFLOG = 7, /**< FreeBSD's PFlog */ 248 258 /* TRACE_TYPE_LEGACY_DEFAULT Obsolete */ 249 TRACE_TYPE_POS = 9, 259 TRACE_TYPE_POS = 9, /**< Packet-over-SONET */ 250 260 /* TRACE_TYPE_LEGACY_ATM Obsolete */ 251 261 /* TRACE_TYPE_LEGACY_ETH Obsolete */ 252 TRACE_TYPE_80211_PRISM = 12, 253 TRACE_TYPE_AAL5 = 13, 262 TRACE_TYPE_80211_PRISM = 12, /**< 802.11 Prism frames */ 263 TRACE_TYPE_AAL5 = 13, /**< ATM Adaptation Layer 5 frames */ 254 264 TRACE_TYPE_DUCK = 14, /**< Pseudo link layer for DUCK packets */ 255 265 TRACE_TYPE_80211_RADIO = 15, /**< Radiotap + 802.11 */ … … 260 270 } libtrace_linktype_t; 261 271 262 /** RT protocol base format identifiers 263 * This is used to say what kind of packet is being sent over the rt protocol 272 /** RT protocol base format identifiers. 273 * This is used to describe the capture format of the packet is being sent 274 * using the RT protocol. 264 275 */ 265 276 enum base_format_t { 266 TRACE_FORMAT_ERF =1, 267 TRACE_FORMAT_PCAP =2, 268 TRACE_FORMAT_PCAPFILE =3, 269 TRACE_FORMAT_WAG =4, 270 TRACE_FORMAT_RT =5, 271 TRACE_FORMAT_LEGACY_ATM =6, 272 TRACE_FORMAT_LEGACY_POS =7, 273 TRACE_FORMAT_LEGACY_ETH =8, 274 TRACE_FORMAT_LINUX_NATIVE =9, 275 TRACE_FORMAT_DUCK =10, 276 TRACE_FORMAT_BPF =11, 277 TRACE_FORMAT_TSH =12, 278 TRACE_FORMAT_ATMHDR =13, 279 TRACE_FORMAT_LEGACY_NZIX =14 277 TRACE_FORMAT_ERF =1, /**< ERF (DAG capture format) */ 278 TRACE_FORMAT_PCAP =2, /**< Live PCAP capture */ 279 TRACE_FORMAT_PCAPFILE =3, /**< PCAP trace file */ 280 TRACE_FORMAT_WAG =4, /**< WAG live capture (Obsolete) */ 281 TRACE_FORMAT_RT =5, /**< RT network protocol */ 282 TRACE_FORMAT_LEGACY_ATM =6, /**< Legacy ERF for ATM capture */ 283 TRACE_FORMAT_LEGACY_POS =7, /**< Legacy ERF for POS capture */ 284 TRACE_FORMAT_LEGACY_ETH =8, /**< Legacy ERF for ETH capture */ 285 TRACE_FORMAT_LINUX_NATIVE =9, /**< Linux native interface capture */ 286 TRACE_FORMAT_DUCK =10, /**< DAG Clock information */ 287 TRACE_FORMAT_BPF =11, /**< BSD native interface capture */ 288 TRACE_FORMAT_TSH =12, /**< TSH trace format */ 289 TRACE_FORMAT_ATMHDR =13, /**< Legacy ATM header capture */ 290 TRACE_FORMAT_LEGACY_NZIX =14 /**< Legacy format used for NZIX traces */ 280 291 }; 281 292 … … 303 314 TRACE_RT_METADATA =18,/**< Packet contains server meta-data */ 304 315 305 TRACE_RT_DATA_SIMPLE = 1000, /**< Trace types that know their link 306 * type 307 */ 316 /** Not actually used - all DATA types begin from this value */ 317 TRACE_RT_DATA_SIMPLE = 1000, 318 319 /** RT is encapsulating an ERF capture record */ 308 320 TRACE_RT_DATA_ERF =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_ERF, 321 /** RT is encapsulating a WAG capture record */ 309 322 TRACE_RT_DATA_WAG =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_WAG, 323 /** RT is encapsulating a Legacy ATM capture record */ 310 324 TRACE_RT_DATA_LEGACY_ATM=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ATM, 325 /** RT is encapsulating a Legacy POS capture record */ 311 326 TRACE_RT_DATA_LEGACY_POS=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_POS, 327 /** RT is encapsulating a Legacy ETH capture record */ 312 328 TRACE_RT_DATA_LEGACY_ETH=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ETH, 329 /** RT is encapsulating a Linux native capture record */ 313 330 TRACE_RT_DATA_LINUX_NATIVE=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_NATIVE, 331 /** RT is encapsulating a BSD native capture record */ 314 332 TRACE_RT_DATA_BPF =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_BPF, 333 /** RT is encapsulating a TSH capture record */ 315 334 TRACE_RT_DATA_TSH =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_TSH, 316 335 /** RT is encapsulating an ATM header capture record */ 317 336 TRACE_RT_DATA_ATMHDR = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ATMHDR, 337 /** RT is encapsulating a Legacy NZIX capture record */ 318 338 TRACE_RT_DATA_LEGACY_NZIX=TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_LEGACY_NZIX, 319 TRACE_RT_DATA_DLT = 2000, /**< Pcap doesn't store the 320 * linktype per packet, and 321 * thus we have to store it 322 * in here. sigh. 323 */ 339 340 /** As PCAP does not store the linktype with the packet, we need to 341 * create a separate RT type for each supported DLT, starting from 342 * this value */ 343 TRACE_RT_DATA_DLT = 2000, 344 /** RT is encapsulating a PCAP capture record with a NULL linktype */ 324 345 TRACE_RT_DLT_NULL =TRACE_RT_DATA_DLT+TRACE_DLT_NULL, 346 /** RT is encapsulating a PCAP capture record with an Ethernet 347 * linktype */ 325 348 TRACE_RT_DLT_EN10MB =TRACE_RT_DATA_DLT+TRACE_DLT_EN10MB, 349 /** RT is encapsulating a PCAP capture record with an 802.11 350 * linktype */ 326 351 TRACE_RT_DLT_IEEE802_11 =TRACE_RT_DATA_DLT+TRACE_DLT_IEEE802_11, 352 /** RT is encapsulating a PCAP capture record with a Linux SLL 353 * linktype */ 327 354 TRACE_RT_DLT_LINUX_SLL =TRACE_RT_DATA_DLT+TRACE_DLT_LINUX_SLL, 355 /** RT is encapsulating a PCAP capture record with a PFlog linktype */ 328 356 TRACE_RT_DLT_PFLOG =TRACE_RT_DATA_DLT+TRACE_DLT_PFLOG, 357 /** RT is encapsulating a PCAP capture record with an AAL5 linktype */ 329 358 TRACE_RT_DLT_ATM_RFC1483 =TRACE_RT_DATA_DLT+TRACE_DLT_ATM_RFC1483, 359 /** Unused value marking the end of the valid range for PCAP RT 360 * encapsulation */ 330 361 TRACE_RT_DATA_DLT_END = 2999, 362 /** Unused value marking the end of the valid range for all RT packet 363 * types */ 331 364 TRACE_RT_LAST = (2<<31) 332 365 } libtrace_rt_types_t; … … 338 371 TRACE_IPPROTO_IGMP = 2, /**< Internet Group Management Protocol */ 339 372 TRACE_IPPROTO_IPIP = 4, /**< IP encapsulated in IP */ 340 TRACE_IPPROTO_TCP = 6, /**< Transmission Control lProtocol */373 TRACE_IPPROTO_TCP = 6, /**< Transmission Control Protocol */ 341 374 TRACE_IPPROTO_UDP = 17, /**< User Datagram Protocol */ 342 375 TRACE_IPPROTO_IPV6 = 41, /**< IPv6 over IPv4 */ 343 TRACE_IPPROTO_ROUTING = 43, /**< IPv6 routing header */376 TRACE_IPPROTO_ROUTING = 43, /**< IPv6 Routing header */ 344 377 TRACE_IPPROTO_FRAGMENT = 44, /**< IPv6 Fragmentation header */ 345 378 TRACE_IPPROTO_RSVP = 46, /**< Resource Reservation Protocol */ 346 379 TRACE_IPPROTO_GRE = 47, /**< General Routing Encapsulation */ 347 380 TRACE_IPPROTO_ESP = 50, /**< Encapsulated Security Payload [RFC2406] */ 348 TRACE_IPPROTO_AH = 51, /**< Aut ehtnication Header [RFC2402*/381 TRACE_IPPROTO_AH = 51, /**< Authentication Header [RFC2402] */ 349 382 TRACE_IPPROTO_ICMPV6 = 58, /**< ICMPv6 */ 350 383 TRACE_IPPROTO_NONE = 59, /**< IPv6 no next header */ … … 354 387 } libtrace_ipproto_t; 355 388 356 /** Ethertypes */389 /** Ethertypes supported by Libtrace */ 357 390 typedef enum { 358 391 /* Numbers <=1500 are of course, LLC/SNAP */ … … 368 401 } libtrace_ethertype_t; 369 402 370 /** The libtrace packet structure , applications shouldn't be403 /** The libtrace packet structure. Applications shouldn't be 371 404 * meddling around in here 372 405 */ 373 406 typedef struct libtrace_packet_t { 374 struct libtrace_t *trace; /**< pointer to the trace */375 void *header; /**< pointer to the framing header */376 void *payload; /**< pointer to the link layer */377 void *buffer; /**< allocated buffer */378 libtrace_rt_types_t type; /**< rtprotocol type for the packet */379 buf_control_t buf_control; /**< who owns the memory*/407 struct libtrace_t *trace; /**< Pointer to the trace */ 408 void *header; /**< Pointer to the framing header */ 409 void *payload; /**< Pointer to the link layer */ 410 void *buffer; /**< Allocated buffer */ 411 libtrace_rt_types_t type; /**< RT protocol type for the packet */ 412 buf_control_t buf_control; /**< Describes memory ownership */ 380 413 int capture_length; /**< Cached capture length */ 381 414 void *l3_header; /**< Cached l3 header */ … … 384 417 385 418 386 /** Trace directions 387 * Note that these are the directions used by convention , more directions419 /** Trace directions. 420 * Note that these are the directions used by convention. More directions 388 421 * are possible, not just these 3, and that they may not conform to this 389 422 * convention. … … 420 453 421 454 /** @name Protocol structures 422 * These convenience structures are here as they are portable ways of dealing423 * with variousprotocols.455 * These convenience structures provide portable versions of the headers 456 * for a variety of protocols. 424 457 * @{ 425 458 */ … … 456 489 typedef struct libtrace_ip6_ext 457 490 { 458 uint8_t nxt; 459 uint8_t len; 491 uint8_t nxt; /**< Next header */ 492 uint8_t len; /**< Length of the current header */ 460 493 } PACKED libtrace_ip6_ext_t; 461 494 462 /** Generic IPv6 header structure */ 495 /** Generic IPv6 header structure 496 * 497 * @note The flow label field also includes the Version and Traffic Class 498 * fields, because we haven't figured out a nice way to deal with fields 499 * crossing byte boundaries on both Big and Little Endian machines */ 463 500 typedef struct libtrace_ip6 464 501 { 465 uint32_t flow; 502 uint32_t flow; /**< Flow label */ 466 503 uint16_t plen; /**< Payload length */ 467 504 uint8_t nxt; /**< Next header */ 468 505 uint8_t hlim; /**< Hop limit */ 469 struct in6_addr ip_src; /**< source address */470 struct in6_addr ip_dst; /**< destaddress */506 struct in6_addr ip_src; /**< Source address */ 507 struct in6_addr ip_dst; /**< Destination address */ 471 508 } PACKED libtrace_ip6_t; 472 509 … … 524 561 struct 525 562 { 526 uint16_t id; 527 uint16_t sequence; 563 uint16_t id; /**< ID of the Echo request */ 564 uint16_t sequence; /**< Sequence number of the Echo request */ 528 565 } echo; /**< Echo Datagram */ 529 566 uint32_t gateway; /**< Gateway Address */ 530 567 struct 531 568 { 532 uint16_t unused; 533 uint16_t mtu; 569 uint16_t unused; /**< Unused */ 570 uint16_t mtu; /**< Next-hop MTU */ 534 571 } frag; /**< Path MTU Discovery */ 535 572 } un; /**< Union for Payloads of Various ICMP Codes */ … … 542 579 uint8_t dsap; /**< Destination Service Access Point */ 543 580 uint8_t ssap; /**< Source Service Access Point */ 544 uint8_t control; 581 uint8_t control; /**< Control field */ 545 582 /* SNAP */ 546 583 LT_BITFIELD32 oui:24; /**< Organisationally Unique Identifier (scope)*/ … … 590 627 /** Captured UNI cell. 591 628 * 592 * Enda nce don't capture the HEC, presumably to keep alignment. This593 * version of the \ref libtrace_atm_cell is used when dealing with dag629 * Endace don't capture the HEC, presumably to keep alignment. This 630 * version of the \ref libtrace_atm_cell is used when dealing with DAG 594 631 * captures of uni cells. 595 632 * … … 606 643 /** Captured NNI cell. 607 644 * 608 * Enda nce don't capture the HEC, presumably to keep alignment. This609 * version of the \ref libtrace_atm_nni_cell is used when dealing with dag645 * Endace don't capture the HEC, presumably to keep alignment. This 646 * version of the \ref libtrace_atm_nni_cell is used when dealing with DAG 610 647 * captures of nni cells. 611 648 * … … 645 682 typedef struct libtrace_80211_t { 646 683 #if BYTE_ORDER == LITTLE_ENDIAN 647 LT_BITFIELD32 protocol:2; 648 LT_BITFIELD32 type:2; 649 LT_BITFIELD32 subtype:4; 684 LT_BITFIELD32 protocol:2; /**< Protocol Version */ 685 LT_BITFIELD32 type:2; /**< Frame Type */ 686 LT_BITFIELD32 subtype:4; /**< Frame Subtype */ 650 687 #else 651 LT_BITFIELD32 subtype:4; 652 LT_BITFIELD32 type:2; 653 LT_BITFIELD32 protocol:2; 688 LT_BITFIELD32 subtype:4; /**< Frame Subtype */ 689 LT_BITFIELD32 type:2; /**< Frame Type */ 690 LT_BITFIELD32 protocol:2; /**< Protocol Version */ 654 691 #endif 655 692 … … 659 696 LT_BITFIELD32 more_frag:1; /**< Packet has more fragments */ 660 697 LT_BITFIELD32 retry:1; /**< Packet is a retry */ 661 LT_BITFIELD32 power:1; 662 LT_BITFIELD32 more_data:1; 663 LT_BITFIELD32 wep:1; 664 LT_BITFIELD32 order:1; 698 LT_BITFIELD32 power:1; /**< Power Management mode */ 699 LT_BITFIELD32 more_data:1; /**< More data is buffered at station */ 700 LT_BITFIELD32 wep:1; /**< WEP encryption indicator */ 701 LT_BITFIELD32 order:1; /**< Strictly-Ordered class indicator */ 665 702 #else 666 LT_BITFIELD32 order:1; 667 LT_BITFIELD32 wep:1; 668 LT_BITFIELD32 more_data:1; 669 LT_BITFIELD32 power:1; 703 LT_BITFIELD32 order:1; /**< Strictly-Ordered class indicator */ 704 LT_BITFIELD32 wep:1; /**< WEP encryption indicator */ 705 LT_BITFIELD32 more_data:1; /**< More data is buffered at station */ 706 LT_BITFIELD32 power:1; /**< Power Management mode */ 670 707 LT_BITFIELD32 retry:1; /**< Packet is a retry */ 671 708 LT_BITFIELD32 more_frag:1; /**< Packet has more fragments */ … … 673 710 LT_BITFIELD32 to_ds:1; /**< Packet to Distribution Service */ 674 711 #endif 675 uint16_t duration; 676 uint8_t mac1[6]; 677 uint8_t mac2[6]; 678 uint8_t mac3[6]; 679 uint16_t SeqCtl; 680 uint8_t mac4[6]; 712 uint16_t duration; /**< Duration value for NAV calculation */ 713 uint8_t mac1[6]; /**< MAC Address 1 */ 714 uint8_t mac2[6]; /**< MAC Address 2 */ 715 uint8_t mac3[6]; /**< MAC Address 3 */ 716 uint16_t SeqCtl; /**< Sequence Control */ 717 uint8_t mac4[6]; /**< MAC Address 4 */ 681 718 } PACKED libtrace_80211_t; 682 719 … … 716 753 */ 717 754 718 /** Create a trace file from a URI755 /** Create an input trace from a URI 719 756 * 720 * @param uri containing a valid libtrace URI721 * @return an opaque pointer to a libtrace_t722 * 723 * Valid URI's are:757 * @param uri A valid libtrace URI to be opened 758 * @return An opaque pointer to a libtrace_t 759 * 760 * Some valid URI's are: 724 761 * - erf:/path/to/erf/file 725 762 * - erf:- (stdin) … … 730 767 * - rt:hostname 731 768 * - rt:hostname:port 732 * - rtclient:hostname (deprecated) 733 * - rtclient:hostname:port (deprecated) 734 * 735 * If an error occured when attempting to open the trace file, an error 736 * trace is returned and trace_get_error should be called to find out 737 * if an error occured, and what that error was. The trace is created in the 738 * configuration state, you must call trace_start to start the capture. 769 * 770 * If an error occured when attempting to open the trace file, a 771 * trace is still returned so trace_is_err() should be called to find out 772 * if an error occured. The trace is created in the configuration state, you 773 * must call trace_start before attempting to read packets from the trace. 739 774 */ 740 775 DLLEXPORT libtrace_t *trace_create(const char *uri); … … 742 777 /** Creates a "dummy" trace file that has only the format type set. 743 778 * 744 * @return an opaque pointer to a (sparsely initialised) libtrace_t 745 * 746 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions 747 * with the dummy trace. Its intended purpose is to act as a packet->trace for 748 * libtrace_packet_t's that are not associated with a libtrace_t structure. 779 * @param uri A valid (but fake) URI indicating the format of the dummy trace that is to be created. 780 * @return An opaque pointer to a (sparsely initialised) libtrace_t 781 * 782 * Only the format portion of the uri parameter matters - the 'file' being 783 * opened does not have to exist. 784 * 785 * @note IMPORTANT: Do not attempt to call trace_read_packet or other such 786 * functions with the dummy trace. Its intended purpose is to provide access 787 * to the format functions where the original trace may no longer exist or is 788 * not the correct format, e.g. reading ERF packets from an RT input. 749 789 */ 750 790 DLLEXPORT libtrace_t *trace_create_dead(const char *uri); … … 752 792 /** Creates a trace output file from a URI. 753 793 * 754 * @param uri the uri string describing the output format and destination755 * @return an opaque pointer to a libtrace_output_t756 * 757 * Valid URI 's are:794 * @param uri The uri string describing the output format and destination 795 * @return An opaque pointer to a libtrace_output_t 796 * 797 * Valid URIs include: 758 798 * - erf:/path/to/erf/file 759 799 * - pcap:/path/to/pcap/file 760 * - wtf:/path/to/wtf/file761 * 762 * If an error occured when attempting to open the output trace, NULL is returned763 * and trace_errno is set. Use trace_perror_output() to get more information800 * 801 * If an error occured when attempting to open the output trace, a trace is 802 * still returned but trace_errno will be set. Use trace_is_err_out() and 803 * trace_perror_output() to get more information. 764 804 */ 765 805 DLLEXPORT libtrace_out_t *trace_create_output(const char *uri); 766 806 767 /** Start the capture807 /** Start an input trace 768 808 * @param libtrace The trace to start 769 809 * @return 0 on success, -1 on failure 770 810 * 771 * This does the actual work with starting the trace capture, and applying 772 * all the config options. This may fail. 811 * This does the actual work of starting the input trace and applying 812 * all the config options. This may fail, returning -1. The libtrace error 813 * handling functions can be used to get more information about what 814 * specifically went wrong. 773 815 */ 774 816 DLLEXPORT int trace_start(libtrace_t *libtrace); 775 817 776 /** Pause the capture818 /** Pauses an input trace 777 819 * @param libtrace The trace to pause 778 820 * @return 0 on success, -1 on failure 779 821 * 780 * This stops a capture in progress and returns you to the configuration 781 * state. Any packets that arrive after trace_pause() has been called 782 * will be discarded. To resume capture, call trace_start(). 822 * This stops an input trace that is in progress and returns you to the 823 * configuration state. Any packets that arrive on a live capture after 824 * trace_pause() has been called will be discarded. To resume the trace, call 825 * trace_start(). 783 826 */ 784 827 DLLEXPORT int trace_pause(libtrace_t *libtrace); … … 788 831 * @return 0 on success, -1 on failure 789 832 * 790 * This does the actual work with starting a trace for write. This generally791 * creates thefile.833 * This does the actual work with starting a trace capable of writing packets. 834 * This generally creates the output file. 792 835 */ 793 836 DLLEXPORT int trace_start_output(libtrace_out_t *libtrace); 794 837 795 /** Valid trace capture options */838 /** Valid configuration options for input traces */ 796 839 typedef enum { 797 TRACE_OPTION_SNAPLEN, /**< Number of bytes captured */ 798 TRACE_OPTION_PROMISC, /**< Capture packets to other hosts */ 799 TRACE_OPTION_FILTER, /**< Apply this filter to all packets */ 800 TRACE_OPTION_META_FREQ, /**< Frequency of meta-data information, e.g. DUCK packets */ 801 /** trace_event ignores gaps between packets when reading traces off disk */ 840 /** Maximum number of bytes to be captured for any given packet */ 841 TRACE_OPTION_SNAPLEN, 842 843 /** If enabled, places a live capture interface into promiscuous mode */ 844 TRACE_OPTION_PROMISC, 845 846 /** Apply this filter to all packets read from this trace */ 847 TRACE_OPTION_FILTER, 848 849 /** Defines the frequency of meta-data reporting, e.g. DUCK packets */ 850 TRACE_OPTION_META_FREQ, 851 852 /* If enabled, the libtrace event API will ignore time gaps between 853 * packets when reading from a trace file */ 802 854 TRACE_OPTION_EVENT_REALTIME 803 855 } trace_option_t; 804 856 805 857 /** Sets an input config option 806 * @param libtrace the trace object to apply the option to807 * @param option the option to set808 * @param value the value to set the option to858 * @param libtrace The trace object to apply the option to 859 * @param option The option to set 860 * @param value The value to set the option to 809 861 * @return -1 if option configuration failed, 0 otherwise 810 862 * This should be called after trace_create, and before trace_start … … 814 866 void *value); 815 867 868 /** Valid configuration options for output traces */ 816 869 typedef enum { 817 TRACE_OPTION_OUTPUT_FILEFLAGS, /**< File flags to open the trace file 818 * with. eg O_APPEND 819 */ 820 TRACE_OPTION_OUTPUT_COMPRESS /**< Compression level, eg 6. */ 870 /** File flags to use when opening an output file, e.g. O_APPEND */ 871 TRACE_OPTION_OUTPUT_FILEFLAGS, 872 /** Compression level: 0 = no compression, 1 = faster compression, 873 * 9 = better compression */ 874 TRACE_OPTION_OUTPUT_COMPRESS 821 875 } trace_option_output_t; 822 876 823 877 /** Sets an output config option 824 878 * 825 * @param libtrace the output trace object to apply the option to826 * @param option the option to set827 * @param value the value to set the option to879 * @param libtrace The output trace object to apply the option to 880 * @param option The option to set 881 * @param value The value to set the option to 828 882 * @return -1 if option configuration failed, 0 otherwise 829 883 * This should be called after trace_create_output, and before … … 835 889 ); 836 890 837 /** Close a trace file, freeing up any resources it may have been using 891 /** Close an input trace, freeing up any resources it may have been using 892 * 893 * @param trace The input trace to be destroyed 838 894 * 839 895 */ 840 896 DLLEXPORT void trace_destroy(libtrace_t *trace); 841 897 842 /** Close a trace file, freeing up any resources it may have been using843 * @param trace trace file to be destroyed898 /** Close a dummy trace file, freeing up any resources it may have been using 899 * @param trace The dummy trace to be destroyed 844 900 */ 845 901 DLLEXPORT void trace_destroy_dead(libtrace_t *trace); 846 902 847 /** Close a trace output file, freeing up any resources it may have been using848 * @param trace the output trace file to be destroyed903 /** Close an output trace, freeing up any resources it may have been using 904 * @param trace The output trace to be destroyed 849 905 */ 850 906 DLLEXPORT void trace_destroy_output(libtrace_out_t *trace); 851 907 852 908 /** Check (and clear) the current error state of an input trace 853 * @param trace the trace file to check the error state on 854 * @return Error report 909 * @param trace The input trace to check the error state on 910 * @return The current error status and message 911 * 855 912 * This reads and returns the current error state and sets the current error 856 913 * to "no error". … … 858 915 DLLEXPORT libtrace_err_t trace_get_err(libtrace_t *trace); 859 916 860 /** Return if there is an error 861 * @param trace the trace file to check the error state on 862 * This does not clear the error status, and only returns true or false. 917 /** Indicate if there has been an error on an input trace 918 * @param trace The input trace to check the error state on 919 * @return true if an error has occurred, false otherwise 920 * 921 * @note This does not clear the error status, and only returns true or false. 863 922 */ 864 923 DLLEXPORT bool trace_is_err(libtrace_t *trace); 865 924 866 /** Output an error message to stderr and clear the error status. 867 * @param trace the trace with the error to output 868 * @param msg the message to prefix to the error 925 /** Outputs the error message for an input trace to stderr and clear the error 926 * status. 927 * @param trace The input trace with the error to output 928 * @param msg The message to prepend to the error 929 * 869 930 * This function does clear the error status. 870 931 */ 871 932 DLLEXPORT void trace_perror(libtrace_t *trace, const char *msg,...) PRINTF(2,3); 872 933 873 /** Check (and clear) the current error state of an output trace 874 * @param trace the output trace file to check the error state on 875 * @return Error report 934 /** Checks (and clears) the current error state for an output trace 935 * @param trace The output trace to check the error state on 936 * @return The current error status and message 937 * 876 938 * This reads and returns the current error state and sets the current error 877 939 * to "no error". … … 879 941 DLLEXPORT libtrace_err_t trace_get_err_output(libtrace_out_t *trace); 880 942 881 /** Return if there is an error 882 * @param trace the trace file to check the error state on 943 /** Indicates if there is an error on an output trace 944 * @param trace The output trace to check the error state on 945 * @return true if an error has occurred, false otherwise. 946 * 883 947 * This does not clear the error status, and only returns true or false. 884 948 */ 885 949 DLLEXPORT bool trace_is_err_output(libtrace_out_t *trace); 886 950 887 /** Output an error message to stderr and clear the error status. 888 * @param trace the trace with the error to output 889 * @param msg the message to prefix to the error 951 /** Outputs the error message for an output trace to stderr and clear the error 952 * status. 953 * @param trace The output trace with the error to output 954 * @param msg The message to prepend to the error 890 955 * This function does clear the error status. 891 956 */ … … 893 958 PRINTF(2,3); 894 959 895 /** Return the number of captured packets960 /** Returns the number of packets observed on an input trace. 896 961 * Includes the number of packets counted as early as possible, before 897 962 * filtering, and includes dropped packets. 898 963 * 899 * @param trace T race to examine900 * @returns number of packets seen at the capture point before filtering.901 * 902 * If th is is not known, thiswill return UINT64_MAX964 * @param trace The input trace to examine 965 * @returns The number of packets seen at the capture point before filtering. 966 * 967 * If the number is not known, this function will return UINT64_MAX 903 968 */ 904 969 DLLEXPORT 905 970 uint64_t trace_get_received_packets(libtrace_t *trace); 906 971 907 /** Return the number of filtered packets 908 * Returns the number of packets that were captured, but discarded for not 909 * matching a trace filter. This includes packets 910 * 911 * @param trace Trace file to examine 912 * @returns the number of packets that were successfully captured, but filtered 913 * 914 * If this is not known, this will return UINT64_MAX 972 /** Returns the number of packets that were captured, but discarded for not 973 * matching a provided filter. 974 * 975 * @param trace The input trace to examine 976 * @returns The number of packets that were successfully captured, but filtered 977 * 978 * If the number is not known, this function will return UINT64_MAX 915 979 */ 916 980 DLLEXPORT 917 981 uint64_t trace_get_filtered_packets(libtrace_t *trace); 918 982 919 /** Return the number of packets that have been dropped for lack of packets 920 * @param trace Trace file to examine 983 /** Returns the number of packets that have been dropped on an input trace due 984 * to lack of buffer space on the capturing device. 985 * 986 * @param trace The input trace to examine 921 987 * @returns The number of packets captured, but dropped due to buffer overruns 988 * 989 * If the number is not known, this function will return UINT64_MAX 922 990 */ 923 991 DLLEXPORT 924 992 uint64_t trace_get_dropped_packets(libtrace_t *trace); 925 993 926 /** Return the number of packets that have been returned to library user 927 * @param trace Trace file to examine 928 * @returns The number of packets returned to the user of the library. 994 /** Returns the number of packets that have been read from the input trace using 995 * trace_read_packet(). 996 * 997 * @param trace The input trace to examine 998 * @returns The number of packets that have been read by the libtrace user. 999 * 1000 * If the number is not known, this function will return UINT64_MAX 929 1001 */ 930 1002 DLLEXPORT … … 942 1014 /** Create a new packet object 943 1015 * 944 * @return apointer to an initialised libtrace_packet_t object1016 * @return A pointer to an initialised libtrace_packet_t object 945 1017 */ 946 1018 DLLEXPORT libtrace_packet_t *trace_create_packet(void); 947 1019 948 /** Copy a packet 949 * @param packet the source packet to copy 950 * @return a new packet which has the same content as the source packet 1020 /** Copy a packet object 1021 * @param packet The source packet to copy 1022 * @return A new packet which has the same content as the source packet 1023 * 951 1024 * @note This always involves a copy, which can be slow. Use of this 952 1025 * function should be avoided where possible. 1026 * 953 1027 * @par The reason you would want to use this function is that a zerocopied 954 * packet from a device is using the devices memory which may be a limited955 * resource. Copying the packet will cause it to be copied into the systems956 * memory.1028 * packet from a device will be stored using memory owned by the device which 1029 * may be a limited resource. Copying the packet will ensure that the packet 1030 * is now stored in memory owned and managed by libtrace. 957 1031 */ 958 1032 DLLEXPORT libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet); 959 1033 960 1034 /** Destroy a packet object 961 * 962 * sideeffect: sets packet to NULL1035 * @param packet The packet to be destroyed 1036 * 963 1037 */ 964 1038 DLLEXPORT void trace_destroy_packet(libtrace_packet_t *packet); 965 1039 966 1040 967 /** Read one packet from the trace 968 * 969 * @param trace the libtrace opaque pointer 970 * @param packet the packet opaque pointer 971 * @return 0 on EOF, negative value on error, number of bytes read when 972 * successful. 973 * 974 * @note the number of bytes read is usually (but not always) the same as 1041 /** Read the next packet from an input trace 1042 * 1043 * @param trace The libtrace opaque pointer for the input trace 1044 * @param packet The packet opaque pointer 1045 * @return 0 on EOF, negative value on error, number of bytes read when successful. 1046 * 1047 * @note The number of bytes read is usually (but not always) the same as 975 1048 * trace_get_framing_length()+trace_get_capture_length() depending on the 976 1049 * trace format. 977 * @note the trace must have been started with trace_start before calling 1050 * 1051 * @note The trace must have been started with trace_start before calling 978 1052 * this function 1053 * 1054 * @note When reading from a live capture, this function will block until a 1055 * packet is observed on the capture interface. The libtrace event API 1056 * (e.g. trace_event()) should be used if non-blocking operation is required. 979 1057 */ 980 1058 DLLEXPORT int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet); … … 984 1062 */ 985 1063 typedef enum { 986 TRACE_EVENT_IOWAIT, /**< Need to block on fd*/987 TRACE_EVENT_SLEEP, /**< Sleep for sometime */988 TRACE_EVENT_PACKET, /**< packet has arrived*/989 TRACE_EVENT_TERMINATE /**< End of trace */1064 TRACE_EVENT_IOWAIT, /**< Wait on the given file descriptor */ 1065 TRACE_EVENT_SLEEP, /**< Sleep for the given amount of time */ 1066 TRACE_EVENT_PACKET, /**< Packet has been read from input trace */ 1067 TRACE_EVENT_TERMINATE /**< End of input trace */ 990 1068 } libtrace_event_t; 991 1069 992 1070 /** Structure returned by libtrace_event explaining what the current event is */ 993 1071 typedef struct libtrace_eventobj_t { 994 libtrace_event_t type; /**< event type (iowait,sleep,packet) */ 995 int fd; /**< if IOWAIT, the fd to sleep on */ 996 double seconds; /**< if SLEEP, the amount of time to sleep for 997 */ 998 int size; /**< if PACKET, the value returned from 999 * trace_read_packet 1000 */ 1072 libtrace_event_t type; /**< Event type (iowait,sleep,packet) */ 1073 1074 /** If the event is IOWAIT, the file descriptor to wait on */ 1075 int fd; 1076 /** If the event is SLEEP, the amount of time to sleep for in seconds */ 1077 double seconds; 1078 /** If the event is PACKET, the value returned by trace_read_packet() */ 1079 int size; 1001 1080 } libtrace_eventobj_t; 1002 1081 1003 /** Processes the next libtrace event 1004 * @param trace the libtrace opaque pointer 1005 * @param packet the libtrace_packet opaque pointer 1006 * @return libtrace_event struct containing the type, and potential 1007 * fd or seconds to sleep on 1082 /** Processes the next libtrace event from an input trace. 1083 * @param trace The libtrace opaque pointer for the input trace 1084 * @param packet The libtrace_packet opaque pointer to use for reading packets 1085 * @return A libtrace_event struct containing the event type and details of the event. 1008 1086 * 1009 1087 * Type can be: 1010 * TRACE_EVENT_IOWAIT Waiting on I/O on fd1011 * TRACE_EVENT_SLEEP Next event in seconds1012 * TRACE_EVENT_PACKET Packet arrived in buffer with size size1088 * TRACE_EVENT_IOWAIT Waiting on I/O on a file descriptor 1089 * TRACE_EVENT_SLEEP Wait a specified amount of time for the next event 1090 * TRACE_EVENT_PACKET Packet was read from the trace 1013 1091 * TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition) 1014 1092 */ … … 1019 1097 /** Write one packet out to the output trace 1020 1098 * 1021 * @param trace the libtrace_out opaque pointer1022 * @param packet the packet opaque pointer1023 * @return the number of bytes written out, if zero or negative then an error has occured.1099 * @param trace The libtrace_out opaque pointer for the output trace 1100 * @param packet The packet opaque pointer of the packet to be written 1101 * @return The number of bytes written out, if zero or negative then an error has occured. 1024 1102 */ 1025 1103 DLLEXPORT int trace_write_packet(libtrace_out_t *trace, libtrace_packet_t *packet); … … 1032 1110 * A packet is divided up into several "layers.": 1033 1111 * 1034 * @li Framing header -- This is the header in a tracefile, or as captured from the network. 1035 * generally this includes capture lengths, wire lengths, timestamps, direction information and 1036 * any other metadata that is part of the capture format. 1112 * @li Framing header -- This is the header provided by the capture format 1113 * itself rather than anything that was sent over the network. This provides 1114 * basic details about the packet record including capture lengths, wire 1115 * lengths, timestamps, direction information and any other metadata that is 1116 * part of the capture format. 1037 1117 * 1038 * @li Metadata header (optional) -- A header containing metadata about a packet that was captured, 1039 * but the metadata was not transmitted over the wire. Some examples include 1040 * RadioTap and Linux_sll headers. This can be retrieved by 1041 * trace_get_packet_meta(), or skipped using trace_get_payload_from_meta(). 1042 * There may be multiple "metadata" headers on a packet. 1043 * 1044 * @li Layer 2/Link layer/Datalink header -- This can be retrieved by trace_get_layer2(), or 1045 * skipped using trace_get_payload_from_layer2(). 1046 * 1047 * @li Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3(). As a convenience 1048 * trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6 header. 1049 * 1050 * @li Layer 5/transport -- These are protocols carried in IPv4/IPv6 frames. These can be 1051 * retrieved using trace_get_transport(). 1118 * @li Metadata header (optional) -- A header containing metadata about a 1119 * packet that was captured, but the metadata was not transmitted over the 1120 * wire. Some examples include RadioTap and Linux_sll headers. This can be 1121 * retrieved by trace_get_packet_meta(), or skipped using 1122 * trace_get_payload_from_meta(). There may be multiple "metadata" headers on 1123 * a packet. 1124 * 1125 * @li Layer 2/Link layer/Datalink header -- This can be retrieved by 1126 * trace_get_layer2(), or skipped using trace_get_payload_from_layer2(). 1127 * 1128 * @li Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3(). As a 1129 * convenience trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6 1130 * header. 1131 * 1132 * @li Layer 5/transport -- These are protocols carried in IPv4/IPv6 frames. 1133 * These can be retrieved using trace_get_transport(). 1052 1134 * 1053 1135 * @{ … … 1060 1142 * Use this function instead of the deprecated trace_get_link(). 1061 1143 * 1062 * @param packet the packet pointer1063 * @param[out] linktype the linktype of the returned pointer1064 * @param[out] remaining the capture length (the number of captured bytes from1144 * @param packet The packet to get the buffer from 1145 * @param[out] linktype The linktype of the returned pointer 1146 * @param[out] remaining The capture length (the number of captured bytes from 1065 1147 * the returned pointer) 1066 * @return apointer to the first byte of the packet1148 * @return A pointer to the first byte of the packet 1067 1149 */ 1068 1150 DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet, 1069 1151 libtrace_linktype_t *linktype, uint32_t *remaining); 1070 1152 1071 /** get a pointer to the link layer1072 * @param packet the packet opaque pointer1073 * 1074 * @return apointer to the link layer, or NULL if there is no link layer1153 /** Get a pointer to the link layer for a given packet 1154 * @param packet The packet to get the link layer for 1155 * 1156 * @return A pointer to the link layer, or NULL if there is no link layer 1075 1157 * 1076 1158 * @deprecated This function is deprecated: Use trace_get_packet_buffer() or 1077 1159 * one of the trace_get_layer*() functions instead. 1078 * @note you should call trace_get_link_type to find out what type of link1079 * layer this is1160 * @note You should call trace_get_link_type to find out what type of link 1161 * layer has been returned to you. 1080 1162 */ 1081 1163 DLLEXPORT SIMPLE_FUNCTION DEPRECATED 1082 1164 void *trace_get_link(const libtrace_packet_t *packet); 1083 1165 1084 /** get a pointer to the IPv4 header (if any) 1085 * @param packet the packet opaque pointer 1086 * 1087 * @return a pointer to the IPv4 header, or NULL if there is no IPv4 header 1166 /** Get a pointer to the IPv4 header (if any) for a given packet 1167 * @param packet The packet to get the IPv4 header for 1168 * 1169 * @return A pointer to the IPv4 header, or NULL if there is no IPv4 header 1170 * 1171 * If a partial IP header is present, i.e. the packet has been truncated before 1172 * the end of the IP header, this function will return NULL. 1088 1173 * 1089 1174 * You should consider using \ref trace_get_layer3 instead of this function.
Note: See TracChangeset
for help on using the changeset viewer.