source: lib/libtrace.h @ fba4ca0

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since fba4ca0 was fba4ca0, checked in by Daniel Lawson <dlawson@…>, 15 years ago

documentation cleanups, moved libtrace_packet_t definition into libtrace_int.h

  • Property mode set to 100644
File size: 21.1 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2004 The University of Waikato, Hamilton, New Zealand.
5 * Authors: Daniel Lawson
6 *          Perry Lorier
7 *         
8 * All rights reserved.
9 *
10 * This code has been developed by the University of Waikato WAND
11 * research group. For further information please see http://www.wand.net.nz/
12 *
13 * libtrace is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * libtrace is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with libtrace; if not, write to the Free Software
25 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 *
27 * $Id$
28 *
29 */
30
31#ifndef LIBTRACE_H
32#define LIBTRACE_H
33
34#include <sys/types.h>
35#include <netinet/in.h>
36
37/** API version as 3 byte hex digits, eg 0xXXYYZZ */
38#define LIBTRACE_API_VERSION 0x100015
39
40#ifdef __cplusplus
41extern "C" { 
42#endif
43/** @file
44 *
45 * @brief Trace file processing library header
46 *
47 * @author Daniel Lawson
48 * @author Perry Lorier
49 *
50 * @version $Id$
51 *
52 * This library provides a per packet interface into a trace file, or a live
53 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
54 * pcap etc.
55 *
56 * @par Usage
57 * See the example/ directory in the source distribution for some simple examples
58 * @par Linking
59 * To use this library you need to link against libtrace by passing -ltrace
60 * to your linker. You may also need to link against a version of libpcap
61 * and of zlib which are compiled for largefile support (if you wish to access
62 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
63 * Woody, at least, does not support large file offsets.
64 *
65 */
66
67#define COLLECTOR_PORT 3435
68
69       
70/** Opaque structure holding information about an output trace */
71struct libtrace_out_t;
72       
73/** Opaque structure holding information about a trace */
74struct libtrace_t;
75       
76/** Opaque structure holding information about a bpf filter */
77struct libtrace_filter_t;
78
79/** Opaque structure holding information about a packet */
80struct libtrace_packet_t;
81
82/** Enumeration of error codes */
83enum {E_NOERROR, E_BAD_FORMAT, E_NO_INIT, E_NO_INIT_OUT, E_URI_LONG, E_URI_NOCOLON, E_INIT_FAILED };
84
85/** Structure for dealing with IP packets */
86struct libtrace_ip
87{
88#if BYTE_ORDER == LITTLE_ENDIAN
89    unsigned int ip_hl:4;               /**< header length */
90    unsigned int ip_v:4;                /**< version */
91#elif BYTE_ORDER == BIG_ENDIAN
92    unsigned int ip_v:4;                /**< version */
93    unsigned int ip_hl:4;               /**< header length */
94#else
95#   error "Adjust your <bits/endian.h> defines"
96#endif
97    u_int8_t ip_tos;                    /**< type of service */
98    u_short ip_len;                     /**< total length */
99    u_short ip_id;                      /**< identification */
100    u_short ip_off;                     /**< fragment offset field */
101#define IP_RF 0x8000                    /**< reserved fragment flag */
102#define IP_DF 0x4000                    /**< dont fragment flag */
103#define IP_MF 0x2000                    /**< more fragments flag */
104#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
105    u_int8_t ip_ttl;                    /**< time to live */
106    u_int8_t ip_p;                      /**< protocol */
107    u_short ip_sum;                     /**< checksum */
108    struct in_addr ip_src;              /**< source address */
109    struct in_addr ip_dst;              /**< dest address */
110} __attribute__ ((__packed__));
111
112/** Structure for dealing with TCP packets */
113struct libtrace_tcp
114  {
115    u_int16_t source;           /**< Source Port */
116    u_int16_t dest;             /**< Destination port */
117    u_int32_t seq;              /**< Sequence number */
118    u_int32_t ack_seq;          /**< Acknowledgement Number */
119#  if BYTE_ORDER == LITTLE_ENDIAN
120    u_int16_t res1:4;           /**< Reserved bits */
121    u_int16_t doff:4;           
122    u_int16_t fin:1;            /**< FIN */
123    u_int16_t syn:1;            /**< SYN flag */
124    u_int16_t rst:1;            /**< RST flag */
125    u_int16_t psh:1;            /**< PuSH flag */
126    u_int16_t ack:1;            /**< ACK flag */
127    u_int16_t urg:1;            /**< URG flag */
128    u_int16_t res2:2;           /**< Reserved */
129#  elif BYTE_ORDER == BIG_ENDIAN
130    u_int16_t doff:4;           
131    u_int16_t res1:4;           /**< Reserved bits */
132    u_int16_t res2:2;           /**< Reserved */
133    u_int16_t urg:1;            /**< URG flag */
134    u_int16_t ack:1;            /**< ACK flag */
135    u_int16_t psh:1;            /**< PuSH flag */
136    u_int16_t rst:1;            /**< RST flag */
137    u_int16_t syn:1;            /**< SYN flag */
138    u_int16_t fin:1;            /**< FIN flag */
139#  else
140#   error "Adjust your <bits/endian.h> defines"
141#  endif
142    u_int16_t window;           /**< Window Size */
143    u_int16_t check;            /**< Checksum */
144    u_int16_t urg_ptr;          /**< Urgent Pointer */
145} __attribute__ ((__packed__));
146
147/** UDP Header for dealing with UDP packets */
148struct libtrace_udp {
149  u_int16_t     source;         /**< Source port */
150  u_int16_t     dest;           /**< Destination port */
151  u_int16_t     len;            /**< Length */
152  u_int16_t     check;          /**< Checksum */
153} __attribute__ ((__packed__));
154
155/** ICMP Header for dealing with icmp packets */
156struct libtrace_icmp
157{
158  u_int8_t type;                /**< message type */
159  u_int8_t code;                /**< type sub-code */
160  u_int16_t checksum;           /**< checksum */
161  union
162  {
163    struct
164    {
165      u_int16_t id;
166      u_int16_t sequence;
167    } echo;                     /**< echo datagram */
168    u_int32_t   gateway;        /**< gateway address */
169    struct
170    {
171      u_int16_t unused;
172      u_int16_t mtu;
173    } frag;                     /**< path mtu discovery */
174  } un;
175} __attribute__ ((__packed__));
176
177/** 802.3 frame */
178struct libtrace_ether
179{
180  u_int8_t ether_dhost[6];      /* destination ether addr */
181  u_int8_t ether_shost[6];      /* source ether addr */
182  u_int16_t ether_type;         /* packet type ID field (next-header) */
183} __attribute__ ((__packed__));
184
185/** 802.1Q frame */
186struct libtrace_8021q
187{
188  u_int8_t  ether_dhost[6];      /* destination eth addr */
189  u_int8_t  ether_shost[6];      /* source ether addr    */
190  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
191  u_int16_t vlan_pri:3;          /* vlan user priority */
192  u_int16_t vlan_cfi:1;          /* vlan format indicator, 0 for ethernet, 1 for token ring */
193  u_int16_t vlan_id:12;          /* vlan id */
194  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
195} __attribute__ ((__packed__));
196
197/** Prints help information for libtrace
198 *
199 * Function prints out some basic help information regarding libtrace,
200 * and then prints out the help() function registered with each input module
201 */
202void trace_help();
203
204/** Gets the output format for a given output trace
205 *
206 * @params libtrace     the output trace to get the name of the format fo
207 * @returns callee-owned null-terminated char* containing the output format
208 *
209 */
210char *trace_get_output_format(struct libtrace_out_t *libtrace);
211
212/** Prints error information
213 *
214 * Prints out a descriptive error message for the currently set trace_err value
215 */
216void trace_perror(char *caller);
217
218/** Create a trace file from a URI
219 *
220 * @params char * containing a valid libtrace URI
221 * @returns opaque pointer to a libtrace_t
222 *
223 * Valid URI's are:
224 *  - erf:/path/to/erf/file
225 *  - erf:/path/to/erf/file.gz
226 *  - erf:/path/to/rtclient/socket
227 *  - erf:-  (stdin)
228 *  - dag:/dev/dagcard                 
229 *  - pcapint:pcapinterface                (eg: pcap:eth0)
230 *  - pcap:/path/to/pcap/file
231 *  - pcap:-
232 *  - rtclient:hostname
233 *  - rtclient:hostname:port
234 *  - wag:-
235 *  - wag:/path/to/wag/file
236 *  - wag:/path/to/wag/file.gz
237 *  - wag:/path/to/wag/socket
238 *
239 *  If an error occured when attempting to open the trace file, NULL is returned
240 *  and trace_errno is set. Use trace_perror() to get more information
241 */
242struct libtrace_t *trace_create(char *uri);
243
244/** Creates a "dummy" trace file that has only the format type set.
245 *
246 * @returns opaque pointer to a (sparsely initialised) libtrace_t
247 *
248 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
249 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
250 * that are not associated with a libtrace_t structure.
251 */
252struct libtrace_t *trace_create_dead(char *uri);
253
254/** Creates a trace output file from a URI.
255 *
256 * @param uri   the uri string describing the output format and destination
257 * @returns opaque pointer to a libtrace_output_t
258 * @author Shane Alcock
259 *
260 * Valid URI's are:
261 *  - gzerf:/path/to/erf/file.gz
262 *  - gzerf:/path/to/erf/file
263 *  - rtserver:hostname
264 *  - rtserver:hostname:port
265 *
266 *  If an error occured when attempting to open the output trace, NULL is returned
267 *  and trace_errno is set. Use trace_perror() to get more information
268 */
269struct libtrace_out_t *trace_output_create(char *uri);
270
271/* Parses an output options string and calls the appropriate function to deal with output options.
272 *
273 * @param libtrace      the output trace object to apply the options to
274 * @param options       the options string
275 * @returns -1 if option configuration failed, 0 otherwise
276 *
277 * @author Shane Alcock
278 */
279int trace_output_config(struct libtrace_out_t *libtrace, char *options);
280
281/** Close a trace file, freeing up any resources it may have been using
282 *
283 */
284void trace_destroy(struct libtrace_t *trace);
285
286void trace_destroy_dead(struct libtrace_t *trace);
287
288/** Close a trace output file, freeing up any resources it may have been using
289 *
290 * @param libtrace      the output trace file to be destroyed
291 *
292 * @author Shane Alcock
293 */
294void trace_output_destroy(struct libtrace_out_t *trace);
295
296/** Read one packet from the trace into buffer
297 *
298 * @param trace         the libtrace opaque pointer
299 * @param packet        the packet opaque pointer
300 * @returns 0 on EOF, negative value on error
301 *
302 */
303int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
304
305/** Write one packet out to the output trace
306 *
307 * @param trace         the libtrace_out opaque pointer
308 * @param packet        the packet opaque pointer
309 * @returns the number of bytes written out, if zero or negative then an error has occured.
310 */
311int trace_write_packet(struct libtrace_out_t *trace, struct libtrace_packet_t *packet);
312
313/** get a pointer to the link layer
314 * @param packet        the packet opaque pointer
315 *
316 * @returns a pointer to the link layer, or NULL if there is no link layer
317 *
318 * @note you should call getLinkType() to find out what type of link layer
319 * this is
320 */
321void *trace_get_link(const struct libtrace_packet_t *packet);
322
323/** get a pointer to the IP header (if any)
324 * @param packet        the packet opaque pointer
325 *
326 * @returns a pointer to the IP header, or NULL if there is not an IP packet
327 */
328struct libtrace_ip *trace_get_ip(const struct libtrace_packet_t *packet);
329
330/** get a pointer to the TCP header (if any)
331 * @param packet        the packet opaque pointer
332 *
333 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
334 */
335struct libtrace_tcp *trace_get_tcp(const struct libtrace_packet_t *packet);
336
337/** get a pointer to the TCP header (if any) given a pointer to the IP header
338 * @param ip            The IP header
339 * @param[out] skipped  An output variable of the number of bytes skipped
340 *
341 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
342 *
343 * Skipped can be NULL, in which case it will be ignored by the program.
344 *
345 * @author Perry Lorier
346 */
347struct libtrace_tcp *trace_get_tcp_from_ip(struct libtrace_ip *ip,int *skipped);
348
349/** get a pointer to the UDP header (if any)
350 * @param packet        the packet opaque pointer
351 *
352 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
353 */
354struct libtrace_udp *trace_get_udp(const struct libtrace_packet_t *packet);
355
356/** get a pointer to the UDP header (if any) given a pointer to the IP header
357 * @param       ip      The IP header
358 * @param[out]  skipped An output variable of the number of bytes skipped
359 *
360 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
361 *
362 * Skipped may be NULL, in which case it will be ignored by this function.
363 */
364struct libtrace_udp *trace_get_udp_from_ip(struct libtrace_ip *ip,int *skipped);
365
366/** get a pointer to the ICMP header (if any)
367 * @param packet        the packet opaque pointer
368 *
369 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
370 */
371struct libtrace_icmp *trace_get_icmp(const struct libtrace_packet_t *packet);
372
373/** get a pointer to the ICMP header (if any) given a pointer to the IP header
374 * @param ip            The IP header
375 * @param[out] skipped  An output variable of the number of bytes skipped
376 *
377 * @returns a pointer to the ICMP header, or NULL if this is not an ICMP packet
378 *
379 * Skipped may be NULL, in which case it will be ignored by this function
380 */
381struct libtrace_icmp *trace_get_icmp_from_ip(struct libtrace_ip *ip,int *skipped);
382
383/** parse an ip or tcp option
384 * @param[in,out] ptr   the pointer to the current option
385 * @param[in,out] len   the length of the remaining buffer
386 * @param[out] type     the type of the option
387 * @param[out] optlen   the length of the option
388 * @param[out] data     the data of the option
389 *
390 * @returns bool true if there is another option (and the fields are filled in)
391 *               or false if this was the last option.
392 *
393 * This updates ptr to point to the next option after this one, and updates
394 * len to be the number of bytes remaining in the options area.  Type is updated
395 * to be the code of this option, and data points to the data of this option,
396 * with optlen saying how many bytes there are.
397 *
398 * @note Beware of fragmented packets.
399 */
400int trace_get_next_option(unsigned char **ptr,int *len,
401                        unsigned char *type,
402                        unsigned char *optlen,
403                        unsigned char **data);
404
405
406/** Get the current time in DAG time format
407 * @param packet        the packet opaque pointer
408 *
409 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
410 * past 1970-01-01, the lower 32bits are partial seconds)
411 * @author Daniel Lawson
412 */
413uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
414
415/** Get the current time in struct timeval
416 * @param packet        the packet opaque pointer
417 *
418 * @returns time that this packet was seen in a struct timeval
419 * @author Daniel Lawson
420 * @author Perry Lorier
421 */ 
422struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
423
424/** Get the current time in floating point seconds
425 * @param packet        the packet opaque pointer
426 *
427 * @returns time that this packet was seen in 64bit floating point seconds
428 * @author Daniel Lawson
429 * @author Perry Lorier
430 */
431double trace_get_seconds(const struct libtrace_packet_t *packet);
432
433/** Get the size of the packet in the trace
434 * @param packet        the packet opaque pointer
435 * @returns the size of the packet in the trace
436 * @author Perry Lorier
437 * @note Due to this being a header capture, or anonymisation, this may not
438 * be the same size as the original packet.  See get_wire_length() for the original
439 * size of the packet.
440 * @note This can (and often is) different for different packets in a trace!
441 * @par
442 *  This is sometimes called the "snaplen".
443 */
444
445int trace_get_capture_length(const struct libtrace_packet_t *packet);
446
447/** Get the size of the packet as it was seen on the wire.
448 * @param packet        the packet opaque pointer
449 * @returns the size of the packet as it was on the wire.
450 * @author Perry Lorier
451 * @author Daniel Lawson
452 * @note Due to the trace being a header capture, or anonymisation this may
453 * not be the same as the Capture Len.
454 */ 
455
456int trace_get_wire_length(const struct libtrace_packet_t *packet);
457
458/** Link layer types
459 */
460typedef enum { 
461       TRACE_TYPE_LEGACY, 
462       TRACE_TYPE_HDLC_POS, 
463       TRACE_TYPE_ETH,
464       TRACE_TYPE_ATM,
465       TRACE_TYPE_80211,
466       TRACE_TYPE_NONE,
467       TRACE_TYPE_LINUX_SLL,
468       TRACE_TYPE_PFLOG
469     } libtrace_linktype_t;
470
471/** Get the type of the link layer
472 * @param packet        the packet opaque pointer
473 * @returns libtrace_linktype_t
474 * @author Perry Lorier
475 * @author Daniel Lawson
476 */
477
478inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
479
480/** Get the destination MAC addres
481 * @param packet        the packet opaque pointer
482 * @returns a pointer to the destination mac, (or NULL if there is no
483 * destination MAC)
484 * @author Perry Lorier
485 */
486uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
487
488/** Get the source MAC addres
489 * @param packet        the packet opaque pointer
490 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
491 * @author Perry Lorier
492 */
493uint8_t *trace_get_source_mac(const struct libtrace_packet_t *packet);
494
495/** Truncate the packet at the suggested length
496 * @param packet        the packet opaque pointer
497 * @param len           the new length of the packet
498 * @returns the new length of the packet, or the original length of the
499 * packet if unchanged
500 * @author Daniel Lawson
501 */
502size_t trace_set_capture_length(struct libtrace_packet_t *packet, size_t size);
503
504/** Set the direction flag, if it has one
505 * @param packet        the packet opaque pointer
506 * @param direction     the new direction (0,1,2,3)
507 * @returns a signed value containing the direction flag, or -1 if this is not supported
508 * @author Daniel Lawson
509 */
510int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
511
512/** Get the direction flag, if it has one
513 * @param packet        the packet opaque pointer
514 * @returns a signed value containing the direction flag, or -1 if this is not supported
515 * The direction is defined as 0 for packets originating locally (ie, outbound)
516 * and 1 for packets originating remotely (ie, inbound).
517 * Other values are possible, which might be overloaded to mean special things
518 * for a special trace.
519 * @author Daniel Lawson
520 */
521int8_t trace_get_direction(const struct libtrace_packet_t *packet);
522
523/** Event types */
524typedef enum {
525        TRACE_EVENT_IOWAIT,
526        TRACE_EVENT_SLEEP,
527        TRACE_EVENT_PACKET,
528        TRACE_EVENT_TERMINATE
529} libtrace_event_t;
530
531/** structure returned by libtrace_event explaining what the current event is */
532struct libtrace_eventobj_t {
533        libtrace_event_t type; /**< event type (iowait,sleep,packet */
534        int fd;                /**< if IOWAIT, the fd to sleep on */
535        double seconds;        /**< if SLEEP, the amount of time to sleep for */
536        int size;              /**< if PACKET, the value returned from trace_read_packet */
537};
538
539/** process a libtrace event
540 * @param trace the libtrace opaque pointer
541 * @param packet the libtrace_packet opaque pointer
542 * @returns libtrace_event struct containing the type, and potential
543 *      fd or seconds to sleep on
544 *
545 * Type can be:
546 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
547 *  TRACE_EVENT_SLEEP   Next event in <seconds>
548 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
549 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
550 */
551struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
552                struct libtrace_packet_t *packet);
553
554/** setup a BPF filter
555 * @param filterstring a char * containing the bpf filter string
556 * @returns opaque pointer pointer to a libtrace_filter_t object
557 * @author Daniel Lawson
558 * @note The filter is not actually compiled at this point, so no correctness
559 * tests are performed here. trace_bpf_setfilter will always return ok, but
560 * if the filter is poorly constructed an error will be generated when the
561 * filter is actually used
562 */
563struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
564
565/** apply a BPF filter
566 * @param filter        the filter opaque pointer
567 * @param packet        the packet opaque pointer
568 * @returns 0 if the filter fails, 1 if it succeeds
569 * @author Daniel Lawson
570 * @note Due to the way BPF filters are built, the filter is not actually compiled
571 * 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.
572 */
573int trace_bpf_filter(struct libtrace_filter_t *filter,
574                const struct libtrace_packet_t *packet);
575
576
577typedef enum {USE_DEST, USE_SOURCE} serverport_t;
578
579/** Get the source port
580 * @param packet        the packet to read from
581 * @returns a port in \em HOST byte order, or equivilent to ports for this
582 * protocol, or 0 if this protocol has no ports.
583 * @author Perry Lorier
584 */
585uint16_t trace_get_source_port(const struct libtrace_packet_t *packet);
586
587/** Get the destination port
588 * @param packet        the packet to read from
589 * @returns a port in \em HOST byte order, or equivilent to ports for this
590 * protocol, or 0 if this protocol has no ports.
591 * @author Perry Lorier
592 */
593uint16_t trace_get_destination_port(const struct libtrace_packet_t *packet);
594
595/** hint at the server port in specified protocol
596 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
597 * @param source        the source port from the packet
598 * @param dest          the destination port from the packet
599 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
600 * @note ports must be in \em HOST byte order!
601 * @author Daniel Lawson
602 */
603int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
604
605/** Takes a uri and splits it into a format and uridata component.
606 * Primarily for internal use but made available for external use.
607 * @param uri           the uri to be parsed
608 * @param format        destination location for the format component of the uri
609 * @returns 0 if an error occured, otherwise returns the uridata component
610 * @author Shane Alcock
611 */
612char *trace_parse_uri(char *uri, char **format);
613#ifdef __cplusplus
614} // extern "C"
615#endif // #ifdef __cplusplus
616#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.