Changes between Initial Version and Version 1 of PortingToLibtrace3


Ignore:
Timestamp:
06/09/06 16:32:27 (16 years ago)
Author:
perry
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PortingToLibtrace3

    v1 v1  
     1== Major API Changes ==
     2There are some changes necessary to software to upgrade from libtrace2 to libtrace3.  Where ever possible we've tried to make these cause a compile warning (or error), or cause an assertion failure the first time they are called.
     3
     4=== Packets ===
     5Packets can no longer be created statically, and now must be created with a libtrace function {{{libtrace_create_packet}}} which takes no parameters.
     6
     7eg:
     8{{{
     9 struct libtrace_packet_t packet;
     10}}}
     11becomes:
     12{{{
     13 libtrace_packet_t *packet = trace_create_packet();
     14}}}
     15and at the end of the program:
     16{{{
     17 trace_destroy_packet(packet);
     18}}}
     19
     20This change was necessary to allow for ZeroCopy, a major speed improvement in libtrace3.
     21
     22=== Traces now must be started ===
     23To allow you to configure a trace traces now must have "trace_start()" called.
     24eg:
     25{{{
     26 libtrace_t *trace=trace_create("pcap:-");
     27}}}
     28becomes:
     29{{{
     30 trace=trace_create("pcap:-");
     31 trace_start(trace);
     32}}}
     33
     34Between trace_create() and trace_start() you may call "trace_config()" to configure some settings on a trace.  Most of the time this isn't necessary.
     35
     36=== Error handling ===
     37To allow for more useful error handling rather than just "failures" libtrace3 now returns an error trace from trace_create if an error occured.  This can be checked with trace_is_err(), and the error may be discovered with trace_get_err() or output with trace_perror().  This allows for multithreaded access to libtrace3 (so long as no single trace object is used between threads).
     38
     39eg:
     40{{{
     41 if (!trace) {
     42   err("failed to open trace\n");
     43 }
     44}}}
     45becomes:
     46{{{
     47 if (trace_is_err(trace)) {
     48   trace_perror(trace,argv[0]);
     49   return 1;
     50 }
     51}}}
     52
     53Note that all libtrace functions can set the error on a trace if an error occurs.
     54
     55=== Filter functions renamed ===
     56trace_bpf_setfilter() was renamed trace_create_filter() and trace_bpf_filter() was renamed trace_apply_filter(), and trace_destroy_filter() was created to release the memory used by filters.
     57
     58This change was made to keep the general naming convention of trace_create_''type''() and trace_destroy_''type''().  The arguments and return time are identical to the old libtrace2 versions.
     59
     60=== Protocol decodes ===
     61trace_get_''something''_from_''something''() functions used to take a pointer that was set to the number of bytes skipped by this protocol.  This has been changed to be the number of bytes remaining in the packet.  This variable is either set to NULL if you know you have enough space.  If it's not NULL it's the number of captured bytes remaining in the packet from the input pointer, and will be updated to be the number of bytes remaining after the header was skipped.
     62
     63=== Avoid IPv4isms ===
     64While trace_get_ip() hasn't been changed, you should try and use the other libtrace accessor functions instead so that your program can be IPv4/IPv6 agnostic.
     65||'''field'''||'''replacement function'''
     66||ip->ip_src||trace_get_source_address()
     67||ip->ip_dst||trace_get_destination_address()
     68||ip->ip_p||trace_get_transport()
     69Also note that you can use trace_get_ip6() to retrieve the IPv6 header.