source: lib/libtrace.h @ 3b8a5ef

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

I hate shane

  • Property mode set to 100644
File size: 24.4 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/** @file
35 *
36 * @brief Trace file processing library header
37 *
38 * @author Daniel Lawson
39 * @author Perry Lorier
40 *
41 * @version $Id$
42 *
43 * 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 * pcap etc.
46 *
47 * @par Usage
48 * See the example/ directory in the source distribution for some simple examples
49 * @par Linking
50 * To use this library you need to link against libtrace by passing -ltrace
51 * to your linker. You may also need to link against a version of libpcap
52 * and of zlib which are compiled for largefile support (if you wish to access
53 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
54 * Woody, at least, does not support large file offsets.
55 *
56 */
57
58#include <sys/types.h>
59#include <netinet/in.h>
60/** API version as 2 byte hex digits, eg 0xXXYYZZ */
61#define LIBTRACE_API_VERSION 0x030000  /* 3.0.00 */
62
63#ifdef __cplusplus
64extern "C" { 
65#endif
66
67/* Function does not depend on anything but its
68 * parameters, used to hint gcc's optimisations
69 */
70#if __GNUC__ >= 3
71#  define SIMPLE_FUNCTION __attribute__((pure))
72#  define UNUSED __attribute__((unused))
73#else
74#  define SIMPLE_FUNCTION
75#  define UNUSED
76#endif
77       
78#define RT_DATA 1
79#define RT_MSG 2
80
81       
82/** Opaque structure holding information about an output trace */
83typedef struct libtrace_out_t libtrace_out_t;
84       
85/** Opaque structure holding information about a trace */
86typedef struct libtrace_t libtrace_t;
87       
88/** Opaque structure holding information about a bpf filter */
89typedef struct libtrace_filter_t libtrace_filter_t;
90
91/** Structure holding status information for a packet */
92typedef struct libtrace_packet_status {
93        uint8_t type;
94        uint8_t reserved;
95        uint16_t message;
96
97} libtrace_packet_status_t;
98
99typedef enum {PACKET, EXTERNAL } buf_control_t;
100/** Structure holding information about a packet */
101#define LIBTRACE_PACKET_BUFSIZE 65536
102typedef struct libtrace_packet_t {
103        struct libtrace_t *trace;
104        void *header;
105        void *payload;
106        void *buffer;
107        size_t size;
108        libtrace_packet_status_t status;
109        buf_control_t buf_control; 
110} __attribute__ ((packed)) libtrace_packet_t;
111                     
112
113/** Enumeration of error codes */
114enum {E_NOERROR, E_BAD_FORMAT, E_NO_INIT, E_NO_INIT_OUT, E_URI_LONG, E_URI_NOCOLON, E_INIT_FAILED };
115
116/** Structure for dealing with IP packets */
117typedef struct libtrace_ip
118{
119#if BYTE_ORDER == LITTLE_ENDIAN
120    unsigned int ip_hl:4;               /**< header length */
121    unsigned int ip_v:4;                /**< version */
122#elif BYTE_ORDER == BIG_ENDIAN
123    unsigned int ip_v:4;                /**< version */
124    unsigned int ip_hl:4;               /**< header length */
125#else
126#   error "Adjust your <bits/endian.h> defines"
127#endif
128    u_int8_t ip_tos;                    /**< type of service */
129    u_short ip_len;                     /**< total length */
130    u_short ip_id;                      /**< identification */
131    u_short ip_off;                     /**< fragment offset field */
132#define IP_RF 0x8000                    /**< reserved fragment flag */
133#define IP_DF 0x4000                    /**< dont fragment flag */
134#define IP_MF 0x2000                    /**< more fragments flag */
135#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
136    u_int8_t ip_ttl;                    /**< time to live */
137    u_int8_t ip_p;                      /**< protocol */
138    u_short ip_sum;                     /**< checksum */
139    struct in_addr ip_src;              /**< source address */
140    struct in_addr ip_dst;              /**< dest address */
141} __attribute__ ((packed)) libtrace_ip_t
142;
143
144/** Structure for dealing with TCP packets */
145typedef struct libtrace_tcp
146  {
147    u_int16_t source;           /**< Source Port */
148    u_int16_t dest;             /**< Destination port */
149    u_int32_t seq;              /**< Sequence number */
150    u_int32_t ack_seq;          /**< Acknowledgement Number */
151#  if BYTE_ORDER == LITTLE_ENDIAN
152    u_int16_t res1:4;           /**< Reserved bits */
153    u_int16_t doff:4;           
154    u_int16_t fin:1;            /**< FIN */
155    u_int16_t syn:1;            /**< SYN flag */
156    u_int16_t rst:1;            /**< RST flag */
157    u_int16_t psh:1;            /**< PuSH flag */
158    u_int16_t ack:1;            /**< ACK flag */
159    u_int16_t urg:1;            /**< URG flag */
160    u_int16_t res2:2;           /**< Reserved */
161#  elif BYTE_ORDER == BIG_ENDIAN
162    u_int16_t doff:4;           
163    u_int16_t res1:4;           /**< Reserved bits */
164    u_int16_t res2:2;           /**< Reserved */
165    u_int16_t urg:1;            /**< URG flag */
166    u_int16_t ack:1;            /**< ACK flag */
167    u_int16_t psh:1;            /**< PuSH flag */
168    u_int16_t rst:1;            /**< RST flag */
169    u_int16_t syn:1;            /**< SYN flag */
170    u_int16_t fin:1;            /**< FIN flag */
171#  else
172#   error "Adjust your <bits/endian.h> defines"
173#  endif
174    u_int16_t window;           /**< Window Size */
175    u_int16_t check;            /**< Checksum */
176    u_int16_t urg_ptr;          /**< Urgent Pointer */
177} __attribute__ ((packed)) libtrace_tcp_t;
178
179/** UDP Header for dealing with UDP packets */
180typedef struct libtrace_udp {
181  u_int16_t     source;         /**< Source port */
182  u_int16_t     dest;           /**< Destination port */
183  u_int16_t     len;            /**< Length */
184  u_int16_t     check;          /**< Checksum */
185} __attribute__ ((packed)) libtrace_udp_t;
186
187/** ICMP Header for dealing with icmp packets */
188typedef struct libtrace_icmp
189{
190  u_int8_t type;                /**< message type */
191  u_int8_t code;                /**< type sub-code */
192  u_int16_t checksum;           /**< checksum */
193  union
194  {
195    struct
196    {
197      u_int16_t id;
198      u_int16_t sequence;
199    } echo;                     /**< echo datagram */
200    u_int32_t   gateway;        /**< gateway address */
201    struct
202    {
203      u_int16_t unused;
204      u_int16_t mtu;
205    } frag;                     /**< path mtu discovery */
206  } un;                         /**< Union for payloads of various icmp codes */
207} __attribute__ ((packed)) libtrace_icmp_t;
208
209/** LLC/SNAP header */
210typedef struct libtrace_llcsnap
211{
212  u_int8_t dsap;
213  u_int8_t ssap;
214  u_int8_t control;
215  u_int32_t oui:24;
216  u_int16_t type;
217} __attribute__ ((packed)) libtrace_llcsnap_t;
218
219/** 802.3 frame */
220typedef struct libtrace_ether
221{
222  u_int8_t ether_dhost[6];      /* destination ether addr */
223  u_int8_t ether_shost[6];      /* source ether addr */
224  u_int16_t ether_type;         /* packet type ID field (next-header) */
225} __attribute__ ((packed)) libtrace_ether_t;
226
227/** 802.1Q frame */
228typedef struct libtrace_8021q
229{
230  u_int8_t  ether_dhost[6];      /* destination eth addr */
231  u_int8_t  ether_shost[6];      /* source ether addr    */
232  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
233  u_int16_t vlan_pri:3;          /* vlan user priority */
234  u_int16_t vlan_cfi:1;          /* vlan format indicator, 0 for ethernet, 1 for token ring */
235  u_int16_t vlan_id:12;          /* vlan id */
236  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
237} __attribute__ ((packed)) libtrace_8021q_t;
238
239/** ATM cell */
240typedef struct libtrace_atm_cell
241{
242  u_int8_t gfc:4;
243  u_int8_t vpi;
244  u_int16_t vci;
245  u_int8_t pt:3;
246  u_int8_t clp:1;
247  u_int8_t hec;
248} __attribute__ ((packed)) libtrace_atm_cell;
249
250/** POS header */
251typedef struct libtrace_pos
252{
253 u_int16_t header;
254 u_int16_t ether_type;
255} __attribute__ ((packed)) libtrace_pos;
256
257/** Prints help information for libtrace
258 *
259 * Function prints out some basic help information regarding libtrace,
260 * and then prints out the help() function registered with each input module
261 */
262void trace_help();
263
264/** Gets the output format for a given output trace
265 *
266 * @param libtrace      the output trace to get the name of the format fo
267 * @returns callee-owned null-terminated char* containing the output format
268 *
269 */
270SIMPLE_FUNCTION
271char *trace_get_output_format(const struct libtrace_out_t *libtrace);
272
273/** Prints error information
274 *
275 * Prints out a descriptive error message for the currently set trace_err value
276 */
277void trace_perror(const char *caller);
278
279/** Create a trace file from a URI
280 *
281 * @param uri containing a valid libtrace URI
282 * @returns opaque pointer to a libtrace_t
283 *
284 * Valid URI's are:
285 *  - erf:/path/to/erf/file
286 *  - erf:/path/to/erf/file.gz
287 *  - erf:/path/to/rtclient/socket
288 *  - erf:-  (stdin)
289 *  - dag:/dev/dagcard                 
290 *  - pcapint:pcapinterface                (eg: pcap:eth0)
291 *  - pcap:/path/to/pcap/file
292 *  - pcap:-
293 *  - rtclient:hostname
294 *  - rtclient:hostname:port
295 *  - wag:-
296 *  - wag:/path/to/wag/file
297 *  - wag:/path/to/wag/file.gz
298 *  - wag:/path/to/wag/socket
299 *
300 *  If an error occured when attempting to open the trace file, NULL is returned
301 *  and trace_errno is set. Use trace_perror() to get more information
302 */
303struct libtrace_t *trace_create(const char *uri);
304
305/** Creates a "dummy" trace file that has only the format type set.
306 *
307 * @returns opaque pointer to a (sparsely initialised) libtrace_t
308 *
309 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
310 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
311 * that are not associated with a libtrace_t structure.
312 */
313struct libtrace_t *trace_create_dead(const char *uri);
314
315/** Creates a trace output file from a URI.
316 *
317 * @param uri   the uri string describing the output format and destination
318 * @returns opaque pointer to a libtrace_output_t
319 * @author Shane Alcock
320 *
321 * Valid URI's are:
322 *  - gzerf:/path/to/erf/file.gz
323 *  - gzerf:/path/to/erf/file
324 *  - rtserver:hostname
325 *  - rtserver:hostname:port
326 *
327 *  If an error occured when attempting to open the output trace, NULL is returned
328 *  and trace_errno is set. Use trace_perror() to get more information
329 */
330struct libtrace_out_t *trace_output_create(const char *uri);
331
332/** Parses an output options string and calls the appropriate function to deal with output options.
333 *
334 * @param libtrace      the output trace object to apply the options to
335 * @param options       the options string
336 * @returns -1 if option configuration failed, 0 otherwise
337 *
338 * @author Shane Alcock
339 */
340int trace_output_config(struct libtrace_out_t *libtrace, char *options);
341
342/** Close a trace file, freeing up any resources it may have been using
343 *
344 */
345void trace_destroy(struct libtrace_t *trace);
346
347/** Close a trace file, freeing up any resources it may have been using
348 * @param trace         trace file to be destroyed
349 */
350void trace_destroy_dead(struct libtrace_t *trace);
351
352/** Close a trace output file, freeing up any resources it may have been using
353 *
354 * @param trace         the output trace file to be destroyed
355 *
356 * @author Shane Alcock
357 */
358void trace_output_destroy(struct libtrace_out_t *trace);
359
360/** Create a new packet object
361 *
362 * @return a pointer to an initialised libtrace_packet_t object
363 */
364struct libtrace_packet_t *trace_packet_create();
365
366/** Destroy a packet object
367 *
368 * sideeffect: sets packet to NULL
369 */
370void trace_packet_destroy(struct libtrace_packet_t **packet);
371
372
373/** Read one packet from the trace into buffer
374 *
375 * @param trace         the libtrace opaque pointer
376 * @param packet        the packet opaque pointer
377 * @returns 0 on EOF, negative value on error
378 *
379 */
380int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
381
382/** Write one packet out to the output trace
383 *
384 * @param trace         the libtrace_out opaque pointer
385 * @param packet        the packet opaque pointer
386 * @returns the number of bytes written out, if zero or negative then an error has occured.
387 */
388int trace_write_packet(struct libtrace_out_t *trace, const struct libtrace_packet_t *packet);
389
390/** get a pointer to the link layer
391 * @param packet        the packet opaque pointer
392 *
393 * @returns a pointer to the link layer, or NULL if there is no link layer
394 *
395 * @note you should call getLinkType() to find out what type of link layer
396 * this is
397 */
398SIMPLE_FUNCTION
399void *trace_get_link(const struct libtrace_packet_t *packet);
400
401/** get a pointer to the IP header (if any)
402 * @param packet        the packet opaque pointer
403 *
404 * @returns a pointer to the IP header, or NULL if there is not an IP packet
405 */
406SIMPLE_FUNCTION
407struct libtrace_ip *trace_get_ip(const struct libtrace_packet_t *packet);
408
409/** get a pointer to the TCP header (if any)
410 * @param packet        the packet opaque pointer
411 *
412 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
413 */
414SIMPLE_FUNCTION
415struct libtrace_tcp *trace_get_tcp(const struct libtrace_packet_t *packet);
416
417/** get a pointer to the TCP header (if any) given a pointer to the IP header
418 * @param ip            The IP header
419 * @param[out] skipped  An output variable of the number of bytes skipped
420 *
421 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
422 *
423 * Skipped can be NULL, in which case it will be ignored by the program.
424 *
425 * @author Perry Lorier
426 */
427SIMPLE_FUNCTION
428struct libtrace_tcp *trace_get_tcp_from_ip(const struct libtrace_ip *ip,int *skipped);
429
430/** get a pointer to the UDP header (if any)
431 * @param packet        the packet opaque pointer
432 *
433 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
434 */
435SIMPLE_FUNCTION
436struct libtrace_udp *trace_get_udp(const struct libtrace_packet_t *packet);
437
438/** get a pointer to the UDP header (if any) given a pointer to the IP header
439 * @param       ip      The IP header
440 * @param[out]  skipped An output variable of the number of bytes skipped
441 *
442 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
443 *
444 * Skipped may be NULL, in which case it will be ignored by this function.
445 */
446SIMPLE_FUNCTION
447struct libtrace_udp *trace_get_udp_from_ip(const struct libtrace_ip *ip,int *skipped);
448
449/** get a pointer to the ICMP header (if any)
450 * @param packet        the packet opaque pointer
451 *
452 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
453 */
454SIMPLE_FUNCTION
455struct libtrace_icmp *trace_get_icmp(const struct libtrace_packet_t *packet);
456
457/** get a pointer to the ICMP header (if any) given a pointer to the IP header
458 * @param ip            The IP header
459 * @param[out] skipped  An output variable of the number of bytes skipped
460 *
461 * @returns a pointer to the ICMP header, or NULL if this is not an ICMP packet
462 *
463 * Skipped may be NULL, in which case it will be ignored by this function
464 */
465SIMPLE_FUNCTION
466struct libtrace_icmp *trace_get_icmp_from_ip(const struct libtrace_ip *ip,int *skipped);
467
468/** parse an ip or tcp option
469 * @param[in,out] ptr   the pointer to the current option
470 * @param[in,out] len   the length of the remaining buffer
471 * @param[out] type     the type of the option
472 * @param[out] optlen   the length of the option
473 * @param[out] data     the data of the option
474 *
475 * @returns bool true if there is another option (and the fields are filled in)
476 *               or false if this was the last option.
477 *
478 * This updates ptr to point to the next option after this one, and updates
479 * len to be the number of bytes remaining in the options area.  Type is updated
480 * to be the code of this option, and data points to the data of this option,
481 * with optlen saying how many bytes there are.
482 *
483 * @note Beware of fragmented packets.
484 */
485int trace_get_next_option(unsigned char **ptr,int *len,
486                        unsigned char *type,
487                        unsigned char *optlen,
488                        unsigned char **data);
489
490
491/** Get the current time in DAG time format
492 * @param packet        the packet opaque pointer
493 *
494 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
495 * past 1970-01-01, the lower 32bits are partial seconds)
496 * @author Daniel Lawson
497 */
498SIMPLE_FUNCTION
499uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
500
501/** Get the current time in struct timeval
502 * @param packet        the packet opaque pointer
503 *
504 * @returns time that this packet was seen in a struct timeval
505 * @author Daniel Lawson
506 * @author Perry Lorier
507 */ 
508SIMPLE_FUNCTION
509struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
510
511/** Get the current time in floating point seconds
512 * @param packet        the packet opaque pointer
513 *
514 * @returns time that this packet was seen in 64bit floating point seconds
515 * @author Daniel Lawson
516 * @author Perry Lorier
517 */
518SIMPLE_FUNCTION
519double trace_get_seconds(const struct libtrace_packet_t *packet);
520
521/** Get the size of the packet in the trace
522 * @param packet        the packet opaque pointer
523 * @returns the size of the packet in the trace
524 * @author Perry Lorier
525 * @note Due to this being a header capture, or anonymisation, this may not
526 * be the same size as the original packet.  See get_wire_length() for the original
527 * size of the packet.
528 * @note This can (and often is) different for different packets in a trace!
529 * @par
530 *  This is sometimes called the "snaplen".
531 */
532SIMPLE_FUNCTION
533int trace_get_capture_length(const struct libtrace_packet_t *packet);
534
535/** Get the size of the packet as it was seen on the wire.
536 * @param packet        the packet opaque pointer
537 * @returns the size of the packet as it was on the wire.
538 * @author Perry Lorier
539 * @author Daniel Lawson
540 * @note Due to the trace being a header capture, or anonymisation this may
541 * not be the same as the Capture Len.
542 */ 
543SIMPLE_FUNCTION
544int trace_get_wire_length(const struct libtrace_packet_t *packet);
545
546/** Get the length of the capture framing headers.
547 * @param packet        the packet opaque pointer
548 * @returns the size of the packet as it was on the wire.
549 * @author Perry Lorier
550 * @author Daniel Lawson
551 * @note this length corresponds to the difference between the size of a
552 * captured packet in memory, and the captured length of the packet
553 */ 
554SIMPLE_FUNCTION
555int trace_get_framing_length(const struct libtrace_packet_t *packet);
556
557
558/** Link layer types
559 * This enumates the various different link types that libtrace understands
560 */
561typedef enum { 
562       TRACE_TYPE_LEGACY,       
563       TRACE_TYPE_HDLC_POS, 
564       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
565       TRACE_TYPE_ATM,
566       TRACE_TYPE_80211,                /**< 802.11 frames */
567       TRACE_TYPE_NONE,
568       TRACE_TYPE_LINUX_SLL,            /**< Linux "null" framing */
569       TRACE_TYPE_PFLOG,                /**< FreeBSD's PFlug */
570       TRACE_TYPE_LEGACY_DEFAULT,
571       TRACE_TYPE_LEGACY_POS,
572       TRACE_TYPE_LEGACY_ATM,
573       TRACE_TYPE_LEGACY_ETH
574     } libtrace_linktype_t;
575
576/** Get the type of the link layer
577 * @param packet        the packet opaque pointer
578 * @returns libtrace_linktype_t
579 * @author Perry Lorier
580 * @author Daniel Lawson
581 */
582SIMPLE_FUNCTION
583inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
584
585/** Get the destination MAC addres
586 * @param packet        the packet opaque pointer
587 * @returns a pointer to the destination mac, (or NULL if there is no
588 * destination MAC)
589 * @author Perry Lorier
590 */
591SIMPLE_FUNCTION
592uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
593
594/** Get the source MAC addres
595 * @param packet        the packet opaque pointer
596 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
597 * @author Perry Lorier
598 */
599SIMPLE_FUNCTION
600uint8_t *trace_get_source_mac(const struct libtrace_packet_t *packet);
601
602/** Truncate the packet at the suggested length
603 * @param packet        the packet opaque pointer
604 * @param size          the new length of the packet
605 * @returns the new length of the packet, or the original length of the
606 * packet if unchanged
607 * @author Daniel Lawson
608 */
609size_t trace_set_capture_length(struct libtrace_packet_t *packet, size_t size);
610
611/** Set the direction flag, if it has one
612 * @param packet        the packet opaque pointer
613 * @param direction     the new direction (0,1,2,3)
614 * @returns a signed value containing the direction flag, or -1 if this is not supported
615 * @author Daniel Lawson
616 */
617int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
618
619/** Get the direction flag, if it has one
620 * @param packet        the packet opaque pointer
621 * @returns a signed value containing the direction flag, or -1 if this is not supported
622 * The direction is defined as 0 for packets originating locally (ie, outbound)
623 * and 1 for packets originating remotely (ie, inbound).
624 * Other values are possible, which might be overloaded to mean special things
625 * for a special trace.
626 * @author Daniel Lawson
627 */
628SIMPLE_FUNCTION
629int8_t trace_get_direction(const struct libtrace_packet_t *packet);
630
631/** Event types
632 * see \ref libtrace_eventobj_t and \ref trace_event
633 */
634typedef enum {
635        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
636        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
637        TRACE_EVENT_PACKET,     /**< packet has arrived */
638        TRACE_EVENT_TERMINATE   /**< End of trace */
639} libtrace_event_t;
640
641/** structure returned by libtrace_event explaining what the current event is */
642struct libtrace_eventobj_t {
643        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
644        int fd;                /**< if IOWAIT, the fd to sleep on */
645        double seconds;        /**< if SLEEP, the amount of time to sleep for */
646        int size;              /**< if PACKET, the value returned from trace_read_packet */
647};
648
649/** process a libtrace event
650 * @param trace the libtrace opaque pointer
651 * @param packet the libtrace_packet opaque pointer
652 * @returns libtrace_event struct containing the type, and potential
653 *      fd or seconds to sleep on
654 *
655 * Type can be:
656 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
657 *  TRACE_EVENT_SLEEP   Next event in seconds
658 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
659 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
660 */
661struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
662                struct libtrace_packet_t *packet);
663
664/** setup a BPF filter
665 * @param filterstring a char * containing the bpf filter string
666 * @returns opaque pointer pointer to a libtrace_filter_t object
667 * @author Daniel Lawson
668 * @note The filter is not actually compiled at this point, so no correctness
669 * tests are performed here. trace_bpf_setfilter will always return ok, but
670 * if the filter is poorly constructed an error will be generated when the
671 * filter is actually used
672 */
673SIMPLE_FUNCTION
674struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
675
676/** apply a BPF filter
677 * @param filter        the filter opaque pointer
678 * @param packet        the packet opaque pointer
679 * @returns 0 if the filter fails, 1 if it succeeds
680 * @author Daniel Lawson
681 * @note Due to the way BPF filters are built, the filter is not actually compiled
682 * 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.
683 */
684int trace_bpf_filter(struct libtrace_filter_t *filter,
685                const struct libtrace_packet_t *packet);
686
687
688/** Which port is the server port */
689typedef enum {
690        USE_DEST,       /**< Destination port is the server port */
691        USE_SOURCE      /**< Source port is the server port */
692} serverport_t;
693
694/** Get the source port
695 * @param packet        the packet to read from
696 * @returns a port in \em HOST byte order, or equivilent to ports for this
697 * protocol, or 0 if this protocol has no ports.
698 * @author Perry Lorier
699 */
700SIMPLE_FUNCTION
701uint16_t trace_get_source_port(const struct libtrace_packet_t *packet);
702
703/** Get the destination port
704 * @param packet        the packet to read from
705 * @returns a port in \em HOST byte order, or equivilent to ports for this
706 * protocol, or 0 if this protocol has no ports.
707 * @author Perry Lorier
708 */
709SIMPLE_FUNCTION
710uint16_t trace_get_destination_port(const struct libtrace_packet_t *packet);
711
712/** hint at the server port in specified protocol
713 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
714 * @param source        the source port from the packet
715 * @param dest          the destination port from the packet
716 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
717 * @note ports must be in \em HOST byte order!
718 * @author Daniel Lawson
719 */
720SIMPLE_FUNCTION
721int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
722
723/** Takes a uri and splits it into a format and uridata component.
724 * Primarily for internal use but made available for external use.
725 * @param uri           the uri to be parsed
726 * @param format        destination location for the format component of the uri
727 * @returns 0 if an error occured, otherwise returns the uridata component
728 * @author Shane Alcock
729 */
730const char *trace_parse_uri(const char *uri, char **format);
731#ifdef __cplusplus
732} // extern "C"
733#endif // #ifdef __cplusplus
734#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.