Porting to Libtrace 3

I sincerely hope that nobody out there is still running libtrace2 code, but there's no harm in keeping this wiki-page around even if it is purely of historical interest these days.

Major API Changes

There are some changes necessary to software to upgrade from libtrace2 to libtrace3. Wherever possible we've tried to make these cause a compile warning (or error), or cause an assertion failure the first time they are called.

Packets

Packets can no longer be created statically, and now must be created with a libtrace function libtrace_create_packet which takes no parameters.

     struct libtrace_packet_t packet;

becomes:

     libtrace_packet_t *packet = trace_create_packet();

and at the end of the program:

     trace_destroy_packet(packet);

This change was necessary to allow for ZeroCopy, a major speed improvement in libtrace3.

Traces now must be started

To allow you to configure a trace traces now must have "trace_start()" called.

     libtrace_t *trace=trace_create("pcapfile:-");

becomes:

     trace=trace_create("pcapfile:-");
     trace_start(trace);

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

Error handling

To 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).

     if (!trace) {
       err("failed to open trace\n");
     }

becomes:

     if (trace_is_err(trace)) {
       trace_perror(trace,argv[0]);
       return 1;
     }

Note that all libtrace functions can set the error on a trace if an error occurs.

Filter functions renamed

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

This change was made to keep the general naming convention of trace_create__type''() and trace_destroy_''type_(). The arguments and return type are identical to the old libtrace2 versions.

Protocol decodes

trace_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 can be 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.

Avoid IPv4isms

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

field	replacement function
ip->ip_src	trace_get_source_address()
ip->ip_dst	trace_get_destination_address()
ip->ip_p	trace_get_transport()

Also note that you can use trace_get_ip6() to retrieve the IPv6 header.