1 /* 2 * This file is part of libtrace 3 * 4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton, 5 * New Zealand. 6 * 7 * Authors: Daniel Lawson 8 * Perry Lorier 9 * Shane Alcock 10 * 11 * All rights reserved. 12 * 13 * This code has been developed by the University of Waikato WAND 14 * research group. For further information please see http://www.wand.net.nz/ 15 * 16 * libtrace is free software; you can redistribute it and/or modify 17 * it under the terms of the GNU General Public License as published by 18 * the Free Software Foundation; either version 2 of the License, or 19 * (at your option) any later version. 20 * 21 * libtrace is distributed in the hope that it will be useful, 22 * but WITHOUT ANY WARRANTY; without even the implied warranty of 23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 24 * GNU General Public License for more details. 25 * 26 * You should have received a copy of the GNU General Public License 27 * along with libtrace; if not, write to the Free Software 28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 29 * 30 * $Id: libtrace_int.h 1851 2013-08-30 01:30:41Z salcock $ 31 * 32 */ 33 34 /** @file 35 * 36 * @brief Header file containing definitions for structures and functions that 37 * are internal 38 * 39 * @author Daniel Lawson 40 * @author Perry Lorier 41 * @author Shane Alcock 42 * 43 * @version $Id: libtrace_int.h 1851 2013-08-30 01:30:41Z salcock $ 44 * 45 * All of the structures and functions defined in this header file are intended 46 * for internal use within Libtrace only. They should not be exported as part 47 * of the library API as we don't want users accessing things like the 48 * contents of the libtrace packet structure directly! 49 */ 50 #ifndef LIBTRACE_INT_H 51 #define LIBTRACE_INT_H 52 53 #ifdef __cplusplus 54 extern "C" { 55 #endif 56 57 #include "config.h" 58 #include "common.h" 59 #include "libtrace.h" 60 #include "wandio.h" 61 #include "lt_bswap.h" 62 63 #ifdef _MSC_VER 64 // warning: deprecated function 65 #pragma warning(disable:4996) 66 // warning: benign redefinitions of types 67 #pragma warning(disable:4142) 68 #endif 69 70 #ifdef HAVE_INTTYPES_H 71 # include <inttypes.h> 72 #else 73 # include "lt_inttypes.h" 74 #endif 75 76 #ifdef HAVE_STDDEF_H 77 # include <stddef.h> 78 #else 79 #ifndef WIN32 80 # error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?" 81 #endif 82 #endif 83 84 85 #include "rt_protocol.h" 86 87 /* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */ 88 #ifdef HAVE_NET_BPF_H 89 # include <net/bpf.h> 90 # define HAVE_BPF 1 91 #else 92 #ifdef HAVE_PCAP_BPF_H 93 # include <pcap-bpf.h> 94 # define HAVE_BPF 1 95 #endif 96 #endif 97 98 #ifdef HAVE_PCAP_H 99 # include <pcap.h> 100 # ifdef HAVE_PCAP_INT_H 101 # include <pcap-int.h> 102 # endif 103 #endif 104 105 #ifdef HAVE_ZLIB_H 106 # include <zlib.h> 107 #endif 108 109 #ifndef HAVE_STRNDUP 110 char *strndup(const char *s, size_t size); 111 #endif 112 113 #ifndef HAVE_STRNCASECMP 114 # ifndef HAVE__STRNICMP 115 /** A local implementation of strncasecmp (as some systems do not have it) */ 116 int strncasecmp(const char *str1, const char *str2, size_t n); 117 # else 118 # define strncasecmp _strnicmp 119 # endif 120 #endif 121 122 #ifndef HAVE_SNPRINTF 123 # ifndef HAVE_SPRINTF_S 124 /** A local implementation of snprintf (as some systems do not have it) */ 125 int snprintf(char *str, size_t size, const char *format, ...); 126 # else 127 # define snprintf sprintf_s 128 # endif 129 #endif 130 131 #include "daglegacy.h" 132 133 #ifdef HAVE_DAG_API 134 # include "dagnew.h" 135 # include "dagapi.h" 136 # if DAG_VERSION == 24 137 # include <erftypes.h> 138 # else 139 # include <daginf.h> 140 # endif 141 # include "erftypes.h" 142 #else 143 # include "dagformat.h" 144 #endif 145 146 #ifdef HAVE_LLVM 147 #include "bpf-jit/bpf-jit.h" 148 #endif 149 150 //#define RP_BUFSIZE 65536U 151 152 /** Data about the most recent event from a trace file */ 153 struct libtrace_event_status_t { 154 /** A libtrace packet to store the packet when a PACKET event occurs */ 155 libtrace_packet_t *packet; 156 /** Time between the timestamp for the current packet and the current 157 * walltime */ 158 double tdelta; 159 /** The timestamp of the previous PACKET event */ 160 double trace_last_ts; 161 /** The size of the current PACKET event */ 162 int psize; 163 /** Whether there is a packet stored in *packet above waiting for an 164 * event to occur */ 165 bool waiting; 166 }; 167 168 /** A libtrace input trace 169 * @internal 170 */ 171 struct libtrace_t { 172 /** The capture format for the input trace */ 173 struct libtrace_format_t *format; 174 /** Details of the most recent PACKET event reported by the trace */ 175 struct libtrace_event_status_t event; 176 /** Pointer to the "global" data for the capture format module */ 177 void *format_data; 178 /** A BPF filter to be applied to all packets read by the trace - 179 * used only if the capture format does not support filters natively */ 180 struct libtrace_filter_t *filter; 181 /** The snap length to be applied to all packets read by the trace - 182 * used only if the capture format does not support snapping natively */ 183 size_t snaplen; 184 /** Count of the number of packets returned to the libtrace user */ 185 uint64_t accepted_packets; 186 /** Count of the number of packets filtered by libtrace */ 187 uint64_t filtered_packets; 188 /** The filename from the uri for the trace */ 189 char *uridata; 190 /** The libtrace IO reader for this trace (if applicable) */ 191 io_t *io; 192 /** Error information for the trace */ 193 libtrace_err_t err; 194 /** Boolean flag indicating whether the trace has been started */ 195 bool started; 196 }; 197 198 /** A libtrace output trace 199 * @internal 200 */ 201 struct libtrace_out_t { 202 /** The capture format for the output trace */ 203 struct libtrace_format_t *format; 204 /** Pointer to the "global" data for the capture format module */ 205 void *format_data; 206 /** The filename for the uri for the output trace */ 207 char *uridata; 208 /** Error information for the output trace */ 209 libtrace_err_t err; 210 /** Boolean flag indicating whether the trace has been started */ 211 bool started; 212 }; 213 214 /** Sets the error status on an input trace 215 * 216 * @param trace The input trace to set the error status for 217 * @param errcode The code for the error - can be a libtrace error code or a regular errno value 218 * @param msg A message to print when reporting the error 219 */ 220 void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 221 222 PRINTF(3,4); 223 /** Sets the error status on an output trace 224 * 225 * @param trace The output trace to set the error status for 226 * @param errcode The code for the error - can be a libtrace error code or a regular errno value 227 * @param msg A message to print when reporting the error 228 */ 229 void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...) 230 PRINTF(3,4); 231 232 /** Clears the cached values for a libtrace packet 233 * 234 * @param packet The libtrace packet that requires a cache reset 235 */ 236 void trace_clear_cache(libtrace_packet_t *packet); 237 238 /** Converts the data provided in buffer into a valid libtrace packet 239 * 240 * @param trace An input trace of the same format as the "packet" 241 * contained in the buffer 242 * @param packet The libtrace packet to prepare 243 * @param buffer A buffer containing the packet data, including the 244 * capture format header 245 * @param rt_type The RT type for the packet that is being prepared 246 * @param flags Used to specify options for the preparation function, 247 * e.g. who owns the packet buffer 248 * 249 * @return -1 if an error occurs, 0 otherwise 250 * 251 * Packet preparation is a tricky concept - the idea is to take the data 252 * pointed to by 'buffer' and treat it as a packet record of the same capture 253 * format as that used by the input trace. The provided libtrace packet then 254 * has its internal pointers and values set to describe the packet record in 255 * the buffer. 256 * 257 * The primary use of this function is to allow the RT packet reader to 258 * easily and safely convert packets from the RT format back into the format 259 * that they were originally captured with., essentially removing the RT 260 * encapsulation. 261 * 262 * We've decided not to make this function available via the exported API 263 * because there are several issues that can arise if it is not used very 264 * carefully and it is not very useful outside of internal contexts anyway. 265 */ 266 int trace_prepare_packet(libtrace_t *trace, libtrace_packet_t *packet, 267 void *buffer, libtrace_rt_types_t rt_type, uint32_t flags); 268 269 /** Flags for prepare_packet functions */ 270 enum { 271 /** The buffer memory has been allocated by libtrace and should be 272 * freed when the packet is destroyed. */ 273 TRACE_PREP_OWN_BUFFER =1, 274 275 /** The buffer memory is externally-owned and must not be freed by 276 * libtrace when the packet is destroyed. */ 277 TRACE_PREP_DO_NOT_OWN_BUFFER =0 278 }; 279 280 281 #ifndef PF_RULESET_NAME_SIZE 282 #define PF_RULESET_NAME_SIZE 16 283 #endif 284 285 #ifndef IFNAMSIZ 286 #define IFNAMSIZ 16 287 #endif 288 289 290 /** A local definition of a PFLOG header */ 291 typedef struct libtrace_pflog_header_t { 292 uint8_t length; 293 sa_family_t af; 294 uint8_t action; 295 uint8_t reason; 296 char ifname[IFNAMSIZ]; 297 char ruleset[PF_RULESET_NAME_SIZE]; 298 uint32_t rulenr; 299 uint32_t subrulenr; 300 uint8_t dir; 301 uint8_t pad[3]; 302 } PACKED libtrace_pflog_header_t; 303 304 305 306 /** A libtrace capture format module */ 307 /* All functions should return -1, or NULL on failure */ 308 struct libtrace_format_t { 309 /** The name of this module, used in the libtrace URI to identify the 310 * capture format */ 311 const char *name; 312 /** The version of this module */ 313 const char *version; 314 /** The RT protocol type of this module */ 315 enum base_format_t type; 316 317 318 /** Given a filename, return if this is the most likely capture format 319 * (used for devices). Used to "guess" the capture format when the 320 * URI is not fully specified. 321 * 322 * @param fname The name of the device or file to examine 323 * @return 1 if the name matches the capture format, 0 otherwise 324 */ 325 int (*probe_filename)(const char *fname); 326 327 /** Given a file, looks at the start of the file to determine if this 328 * is the capture format. Used to "guess" the capture format when the 329 * URI is not fully specified. 330 * 331 * @param io An open libtrace IO reader for the file to check 332 * @return 1 if the file matches the capture format, 0 otherwise 333 */ 334 int (*probe_magic)(io_t *io); 335 336 /** Initialises an input trace using the capture format. 337 * 338 * @param libtrace The input trace to be initialised 339 * @return 0 if successful, -1 in the event of error 340 */ 341 int (*init_input)(libtrace_t *libtrace); 342 343 /** Applies a configuration option to an input trace. 344 * 345 * @param libtrace The input trace to apply the option to 346 * @param option The option that is being configured 347 * @param value A pointer to the value that the option is to be 348 * set to 349 * @return 0 if successful, -1 if the option is unsupported or an error 350 * occurs 351 */ 352 int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value); 353 /** Starts or unpauses an input trace - note that this function is 354 * often the one that opens the file or device for reading. 355 * 356 * @param libtrace The input trace to be started or unpaused 357 * @return 0 if successful, -1 in the event of error */ 358 int (*start_input)(libtrace_t *libtrace); 359 360 /** Pauses an input trace - this function should close or detach the 361 * file or device that is being read from. 362 * 363 * @param libtrace The input trace to be paused 364 * @return 0 if successful, -1 in the event of error 365 */ 366 int (*pause_input)(libtrace_t *libtrace); 367 368 /** Initialises an output trace using the capture format. 369 * 370 * @param libtrace The output trace to be initialised 371 * @return 0 if successful, -1 in the event of error 372 */ 373 int (*init_output)(libtrace_out_t *libtrace); 374 375 /** Applies a configuration option to an output trace. 376 * 377 * @param libtrace The output trace to apply the option to 378 * @param option The option that is being configured 379 * @param value A pointer to the value that the option is to be 380 * set to 381 * @return 0 if successful, -1 if the option is unsupported or an error 382 * occurs 383 * */ 384 int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value); 385 386 /** Starts an output trace - note that this function is often the one 387 * that opens the file or device for writing. 388 * 389 * @param libtrace The output trace to be started 390 * @return 0 if successful, -1 if an error occurs 391 * 392 * There is no pause for output traces, as writing is not performed 393 * asynchronously. 394 */ 395 int (*start_output)(libtrace_out_t *libtrace); 396 397 /** Concludes an input trace and cleans up the capture format data. 398 * 399 * @param libtrace The input trace to be concluded 400 * @return 0 if successful, -1 if an error occurs 401 * 402 * Libtrace will call the pause_input function if the input trace is 403 * currently active prior to calling this function. 404 */ 405 int (*fin_input)(libtrace_t *libtrace); 406 407 /** Concludes an output trace and cleans up the capture format data. 408 * 409 * @param libtrace The output trace to be concluded 410 * @return 0 if successful, -1 if an error occurs 411 */ 412 int (*fin_output)(libtrace_out_t *libtrace); 413 414 /** Reads the next packet from an input trace into the provided packet 415 * structure. 416 * 417 * @param libtrace The input trace to read from 418 * @param packet The libtrace packet to read into 419 * @return The size of the packet read (in bytes) including the capture 420 * framing header, or -1 if an error occurs. 0 is returned in the 421 * event of an EOF. 422 * 423 * If no packets are available for reading, this function should block 424 * until one appears or return 0 if the end of a trace file has been 425 * reached. 426 */ 427 int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet); 428 429 /** Converts a buffer containing a packet record into a libtrace packet 430 * 431 * @param libtrace An input trace in the capture format for the 432 * packet 433 * @param packet A libtrace packet to put the prepared packet 434 * into 435 * @param buffer The buffer containing the packet record 436 * (including the capture format header) 437 * @param rt_type The RT type for the packet 438 * @param flags Flags describing properties that should be 439 * applied to the new packet 440 * @return 0 if successful, -1 if an error occurs. 441 * 442 * Updates internal trace and packet details, such as payload pointers, 443 * loss counters and packet types to match the packet record provided 444 * in the buffer. This is a zero-copy function. 445 * 446 * Intended (at this stage) only for internal use, particularly by 447 * RT which needs to decapsulate RT packets */ 448 int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet, 449 void *buffer, libtrace_rt_types_t rt_type, 450 uint32_t flags); 451 452 /** Frees any resources allocated by the capture format module for a 453 * libtrace packet. 454 * 455 * @param The packet to be finalised 456 * */ 457 void (*fin_packet)(libtrace_packet_t *packet); 458 459 /** Write a libtrace packet to an output trace. 460 * 461 * @param libtrace The output trace to write the packet to 462 * @param packet The packet to be written out 463 * @return The number of bytes written, or -1 if an error occurs 464 */ 465 int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet); 466 /** Returns the libtrace link type for a packet. 467 * 468 * @param packet The packet to get the link type for 469 * @return The libtrace link type, or -1 if this link type is unknown 470 */ 471 libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet); 472 473 /** Returns the direction of a packet. 474 * 475 * @param packet The packet to get the direction for 476 * @return The direction of the packet, or -1 if no direction tag is 477 * present or an error occurs 478 */ 479 libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet); 480 481 /** Sets the direction of a packet. 482 * 483 * @param packet The packet to set the direction for 484 * @param direction The direction to assign to the packet 485 * @return The updated direction for the packet, or -1 if an error 486 * occurs 487 * 488 * @note Some capture formats do not feature direction tagging, so it 489 * will not make sense to implement a set_direction function for them. 490 */ 491 libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction); 492 493 /** Returns the timestamp for a packet in the ERF timestamp format. 494 * 495 * @param packet The packet to get the timestamp from 496 * @return The 64-bit ERF timestamp 497 * 498 * @note Each format must implement at least one of the four "get 499 * timestamp" functions. 500 * 501 * If not implemented, libtrace will convert the result of one of the 502 * other timestamp functions into the appropriate format instead. 503 * This means each capture format only needs to implement the most 504 * sensible of the four and let libtrace handle any conversions. 505 * 506 */ 507 uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet); 508 509 /** Returns the timestamp for a packet in the timeval format 510 * 511 * @param packet The packet to get the timestamp from 512 * @return The timestamp from the packet as a timeval 513 * 514 * @note Each format must implement at least one of the four "get 515 * timestamp" functions. 516 * 517 * If not implemented, libtrace will convert the result of one of the 518 * other timestamp functions into the appropriate format instead. 519 * This means each capture format only needs to implement the most 520 * sensible of the four and let libtrace handle any conversions. 521 */ 522 struct timeval (*get_timeval)(const libtrace_packet_t *packet); 523 524 /** Returns the timestamp for a packet in the timespec format. 525 * 526 * @param packet The packet to get the timestamp from 527 * @return The timestamp from the packet as a timespec 528 * 529 * @note Each format must implement at least one of the four "get 530 * timestamp" functions. 531 * 532 * If not implemented, libtrace will convert the result of one of the 533 * other timestamp functions into the appropriate format instead. 534 * This means each capture format only needs to implement the most 535 * sensible of the four and let libtrace handle any conversions. 536 */ 537 struct timespec (*get_timespec)(const libtrace_packet_t *packet); 538 539 /** Returns the timestamp for a packet in floating point seconds. 540 * 541 * @param packet The packet to get the timestamp from 542 * @return The timestamp from the packet as a floating point number of 543 * seconds since 1970-01-01 00:00:00 UTC 544 * 545 * @note Each format must implement at least one of the four "get 546 * timestamp" functions. 547 * 548 * If not implemented, libtrace will convert the result of one of the 549 * other timestamp functions into the appropriate format instead. 550 * This means each capture format only needs to implement the most 551 * sensible of the four and let libtrace handle any conversions. 552 */ 553 double (*get_seconds)(const libtrace_packet_t *packet); 554 555 /** Moves the read pointer to a certain ERF timestamp within an input 556 * trace file. 557 * 558 * @param trace The input trace to seek within 559 * @param timestamp The timestamp to seek to, as an ERF timestamp 560 * 561 * @return 0 on success, -1 on failure. 562 * 563 * The next packet read from this trace will now be the first packet 564 * to have a timestamp equal to or greater than the provided timestamp. 565 * 566 * @note Each format that supports seeking must implement at least one 567 * of the seek functions. 568 * 569 * If not implemented, libtrace will convert the timestamp into the 570 * appropriate format to use a seek function that has been implemented. 571 * This means each capture format only needs to implement the seek 572 * function that matches the native timestamp format for that capture. 573 * 574 */ 575 int (*seek_erf)(libtrace_t *trace, uint64_t timestamp); 576 /** Moves the read pointer to a certain timestamp represented using a 577 * timeval within an input trace file. 578 * 579 * @param trace The input trace to seek within 580 * @param timestamp The timestamp to seek to, as a timeval 581 * 582 * @return 0 on success, -1 on failure. 583 * 584 * The next packet read from this trace will now be the first packet 585 * to have a timestamp equal to or greater than the provided timestamp. 586 * 587 * @note Each format that supports seeking must implement at least one 588 * of the seek functions. 589 * 590 * If not implemented, libtrace will convert the timestamp into the 591 * appropriate format to use a seek function that has been implemented. 592 * This means each capture format only needs to implement the seek 593 * function that matches the native timestamp format for that capture. 594 * 595 */ 596 int (*seek_timeval)(libtrace_t *trace, struct timeval tv); 597 598 /** Moves the read pointer to a certain timestamp represented using 599 * floating point seconds within an input trace file. 600 * 601 * @param trace The input trace to seek within 602 * @param timestamp The timestamp to seek to, as floating point 603 * seconds since 1970-01-01 00:00:00 UTC 604 * 605 * @return 0 on success, -1 on failure. 606 * 607 * The next packet read from this trace will now be the first packet 608 * to have a timestamp equal to or greater than the provided timestamp. 609 * 610 * @note Each format that supports seeking must implement at least one 611 * of the seek functions. 612 * 613 * If not implemented, libtrace will convert the timestamp into the 614 * appropriate format to use a seek function that has been implemented. 615 * This means each capture format only needs to implement the seek 616 * function that matches the native timestamp format for that capture. 617 * 618 */ 619 int (*seek_seconds)(libtrace_t *trace, double seconds); 620 621 /** Returns the payload length of the captured packet record. 622 * 623 * @param packet The packet to get the capture length from 624 * @return The capture length for the packet, or -1 if an error occurs 625 * 626 * Capture length is the current size of the packet record itself, 627 * following any truncation that may have occurred during the capture 628 * process. This length does not include the capture format framing 629 * header. 630 */ 631 int (*get_capture_length)(const libtrace_packet_t *packet); 632 633 /** Returns the original length of the packet as it was on the wire. 634 * 635 * @param packet The packet to get the wire length from 636 * @return The length of the packet on the wire at the time of capture, 637 * or -1 if an error occurs 638 * 639 * Wire length is the original size of the packet prior to any 640 * truncation that may have occurred as part of the capture process. 641 * This length does not include the capture format framing header. 642 */ 643 int (*get_wire_length)(const libtrace_packet_t *packet); 644 645 /** Returns the length of the capture format framing header 646 * 647 * @param packet The packet to get the framing length from 648 * @return The length of the framing header, or -1 if an error occurs 649 * 650 * The framing header is the extra metadata that the capture process 651 * records about a packet. The framing length does not include any 652 * of the packet payload itself. The total size of the packet record 653 * can be calculated be adding this value with the capture length. 654 */ 655 int (*get_framing_length)(const libtrace_packet_t *packet); 656 657 /** Sets the capture length for a packet. 658 * 659 * @param packet The packet to adjust the capture length for. 660 * @param size The new capture length 661 * @return The new capture length of the packet, or -1 if an error 662 * occurs 663 * 664 * @note This function should only reduce the capture length. If the 665 * provided length is larger than the current capture length, -1 should 666 * be returned. 667 */ 668 size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size); 669 /** Returns the number of packets observed by an input trace. 670 * 671 * @param trace The input trace to get the packet count for 672 * @return The number of packets observed by an input trace, or 673 * UINT64_MAX if the number is unknown 674 * 675 * This count includes packets that have been filtered and dropped. 676 */ 677 uint64_t (*get_received_packets)(libtrace_t *trace); 678 679 /** Returns the number of packets filtered by an input trace. 680 * 681 * @param trace The input trace to get the filtered count for 682 * @return The number of packets filtered by the input trace, or 683 * UINT64_MAX if the number is unknown 684 * 685 */ 686 uint64_t (*get_filtered_packets)(libtrace_t *trace); 687 688 /** Returns the number of packets dropped by an input trace. 689 * 690 * @param trace The input trace to get the dropped count for 691 * @return The number of packets dropped by the input trace, or 692 * UINT64_MAX if the number is unknown 693 * 694 */ 695 uint64_t (*get_dropped_packets)(libtrace_t *trace); 696 697 /** Returns the number of packets captured and returned by an input 698 * trace. 699 * 700 * @param trace The input trace to get the capture count for 701 * @return The number of packets returned to the libtrace user, or 702 * UINT64_MAX if the number is unknown 703 * 704 * This is the number of packets that have been successfully returned 705 * to the libtrace user via the read_packet() function. 706 * 707 */ 708 uint64_t (*get_captured_packets)(libtrace_t *trace); 709 710 /** Returns the file descriptor used by the input trace. 711 * 712 * @param trace The input trace to get the file descriptor for 713 * @return The file descriptor used by the input trace to read packets 714 * 715 */ 716 int (*get_fd)(const libtrace_t *trace); 717 718 /** Returns the next libtrace event for the input trace. 719 * 720 * @param trace The input trace to get the next event from 721 * @param packet A libtrace packet to read a packet into 722 * @return A libtrace event describing the event that occured 723 * 724 * The event API allows for non-blocking reading of packets from an 725 * input trace. If a packet is available and ready to be read, a packet 726 * event should be returned. Otherwise a sleep or fd event should be 727 * returned to indicate that the caller needs to wait. If the input 728 * trace has an error or reaches EOF, a terminate event should be 729 * returned. 730 */ 731 struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet); 732 733 /** Prints some useful help information to standard output. */ 734 void (*help)(void); 735 736 /** Next pointer, should always be NULL - used by the format module 737 * manager. */ 738 struct libtrace_format_t *next; 739 }; 740 741 /** The list of registered capture formats */ 742 //extern struct libtrace_format_t *form; 743 744 /** Specifies whether any blocking packet readers should cease reading 745 * immediately 746 */ 747 extern int libtrace_halt; 748 749 /** Registers a new capture format module. 750 * 751 * @param format The format module to be registered 752 */ 753 void register_format(struct libtrace_format_t *format); 754 755 /** Converts a PCAP DLT into a libtrace link type. 756 * 757 * @param linktype The PCAP DLT to be converted 758 * @return The libtrace link type that is equivalent to the provided DLT, or 759 * -1 if the DLT is unknown 760 */ 761 libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype); 762 763 /** Converts a PCAP DLT into an RT protocol type. 764 * 765 * @param linktype The PCAP DLT to be converted 766 * @return The RT type that is equivalent to the provided DLT 767 */ 768 libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype); 769 770 /** Converts a libtrace link type into a PCAP linktype. 771 * 772 * @param type The libtrace link type to be converted 773 * @return The PCAP linktype that is equivalent to the provided libtrace link 774 * type, or -1 if the link type is unknown 775 */ 776 libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type); 777 778 /** Converts a libtrace link type into a PCAP DLT. 779 * 780 * @param type The libtrace link type to be converted 781 * @return The PCAP DLT that is equivalent to the provided libtrace link 782 * type, or -1 if the link type is unknown 783 */ 784 libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type); 785 786 /** Converts an RT protocol type into a PCAP DLT. 787 * 788 * @param rt_type The RT type to be converted 789 * @return The PCAP DLT that is equivalent to the provided RT protocol 790 */ 791 libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type); 792 793 /** Converts a PCAP DLT into an RT protocol type for the BPF format. 794 * 795 * @param linktype The PCAP DLT to be converted 796 * @return The RT type that is equivalent to the provided DLT for BPF 797 */ 798 libtrace_rt_types_t bpf_linktype_to_rt(libtrace_dlt_t linktype); 799 800 /** Converts an ERF type into a libtrace link type. 801 * 802 * @param erf The ERF type to be converted 803 * @return The libtrace link type that is equivalent to the provided ERF type, 804 * or -1 if the ERF type is unknown 805 */ 806 libtrace_linktype_t erf_type_to_libtrace(uint8_t erf); 807 808 /** Converts a libtrace link type into an ERF type. 809 * 810 * @param linktype The libtrace link type to be converted 811 * @return The ERF type that is equivalent to the provided libtrace link type, 812 * or -1 if the link type cannot be matched to an ERF type. 813 */ 814 uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype); 815 816 /** Converts an ARPHRD type into a libtrace link type. 817 * 818 * @param arphrd The ARPHRD type to be converted 819 * @return The libtrace link type that is equivalent to the provided ARPHRD 820 * type, or -1 if the ARPHRD type is unknown 821 */ 822 libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd); 823 824 /** Converts a libtrace link type into an ARPHRD type. 825 * 826 * @param type The libtrace link type to be converted 827 * @return The ARPHRD type that is equivalent to the provided libtrace link 828 * type, or -1 if the link type cannot be matched to an ARPHRD type 829 */ 830 unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type); 831 832 /** Converts a libtrace packet to the Linux SLL type. 833 * 834 * @param packet The packet to be promoted 835 * 836 * @note This will involve memcpy() so use sparingly. 837 * 838 * This function prepends a Linux SLL header to a packet so that we can store 839 * direction tagging information. 840 */ 841 void promote_packet(libtrace_packet_t *packet); 842 843 /** Attempts to demote a packet by removing the first header. 844 * 845 * @param packet The packet to be demoted 846 * @return True if the packet was demoted, false otherwise. 847 * 848 * Essentially the opposite of promote_packet, except that it will also remove 849 * an ATM header as well as Linux SLL. 850 * 851 */ 852 bool demote_packet(libtrace_packet_t *packet); 853 854 /** Returns a pointer to the header following a Linux SLL header. 855 * 856 * @param link A pointer to the Linux SLL header to be skipped 857 * @param[out] arphrd_type The arp hardware type of the packet 858 * @param[out] next_header The ethertype of the next header 859 * @param[in,out] remaining Updated with the number of captured bytes 860 * remaining 861 * @return A pointer to the header following the Linux SLL header, or NULL if 862 * no subsequent header is present. 863 * 864 * Remaining must point to the number of bytes captured from the Linux SLL 865 * header and beyond. It will be decremented by the number of bytes skipped 866 * to find the payload. 867 * 868 * If the Linux SLL header is complete but there are zero bytes of payload 869 * after the end of the header, a pointer to where the payload would be is 870 * returned and remaining will be set to zero. If the Linux SLL header is 871 * incomplete (truncated), then NULL is returned and remaining will be set to 872 * 0. Therefore, it is very important to check the value of remaining after 873 * calling this function. 874 */ 875 void *trace_get_payload_from_linux_sll(const void *link, 876 uint16_t *arphrd_type, 877 uint16_t *next_header, 878 uint32_t *remaining); 879 880 /** Returns a pointer to the header following an ATM header. 881 * 882 * @param link A pointer to the ATM header to be skipped 883 * @param[out] type The ethertype of the next header 884 * @param[in,out] remaining Updated with the number of captured bytes 885 * remaining 886 * @return A pointer to the header following the ATM header, or NULL if 887 * no subsequent header is present. 888 * 889 * Remaining must point to the number of bytes captured from the ATM header 890 * and beyond. It will be decremented by the number of bytes skipped to find 891 * the payload. 892 * 893 * If the ATM header is complete but there are zero bytes of payload 894 * after the end of the header, a pointer to where the payload would be is 895 * returned and remaining will be set to zero. If the ATM header is 896 * incomplete (truncated), then NULL is returned and remaining will be set to 897 * 0. Therefore, it is very important to check the value of remaining after 898 * calling this function. 899 */ 900 DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 901 uint32_t *remaining); 902 903 904 #ifdef HAVE_BPF 905 /* A type encapsulating a bpf filter 906 * This type covers the compiled bpf filter, as well as the original filter 907 * string 908 * 909 */ 910 911 /** Internal representation of a BPF filter */ 912 struct libtrace_filter_t { 913 struct bpf_program filter; /**< The BPF program itself */ 914 char * filterstring; /**< The filter string */ 915 int flag; /**< Indicates if the filter is valid */ 916 struct bpf_jit_t *jitfilter; 917 }; 918 #else 919 /** BPF not supported by this system, but we still need to define a structure 920 * for the filter */ 921 struct libtrace_filter_t {}; 922 #endif 923 924 /** Local definition of a PCAP header */ 925 typedef struct libtrace_pcapfile_pkt_hdr_t { 926 uint32_t ts_sec; /* Seconds portion of the timestamp */ 927 uint32_t ts_usec; /* Microseconds portion of the timestamp */ 928 uint32_t caplen; /* Capture length of the packet */ 929 uint32_t wirelen; /* The wire length of the packet */ 930 } libtrace_pcapfile_pkt_hdr_t; 931 932 #ifdef HAVE_DAG 933 /** Constructor for the DAG format module */ 934 void dag_constructor(void); 935 #endif 936 /** Constructor for the ERF format module */ 937 void erf_constructor(void); 938 /** Constructor for the TSH format module */ 939 void tsh_constructor(void); 940 /** Constructor for the Legacy DAG format module */ 941 void legacy_constructor(void); 942 /** Constructor for the Linux Native format module */ 943 void linuxnative_constructor(void); 944 /** Constructor for the PCAP format module */ 945 void pcap_constructor(void); 946 /** Constructor for the PCAP File format module */ 947 void pcapfile_constructor(void); 948 /** Constructor for the RT format module */ 949 void rt_constructor(void); 950 /** Constructor for the DUCK format module */ 951 void duck_constructor(void); 952 /** Constructor for the ATM Header format module */ 953 void atmhdr_constructor(void); 954 #ifdef HAVE_BPF 955 /** Constructor for the BPF format module */ 956 void bpf_constructor(void); 957 #endif 958 #if HAVE_DPDK 959 /** Constructor for Intels DPDK format module */ 960 void dpdk_constructor(void); 961 #endif 962 963 /** Extracts the RadioTap flags from a wireless link header 964 * 965 * @param link A pointer to the wireless link header 966 * @param linktype The link type of the wireless header 967 * @param[out] flags Space to store the extracted flags 968 * @return True if libtrace was able to extract flags from the link header, 969 * false otherwise. 970 * 971 * This function has been left internal because it is not portable across 972 * drivers. 973 */ 974 bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags); 975 #define TRACE_RADIOTAP_F_FCS 0x10 976 977 #ifdef __cplusplus 978 } 979 #endif 980 981 #endif /* LIBTRACE_INT_H */ 982