source: lib/libtrace.h @ 3840760

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

update to version 3.0.0
zero-copy patch - trace.c updated with new trace_create_packet() etc
format_*.c updated with zero-copy codepath

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