source: lib/libtrace.h @ 3b8338b

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

adding typedef to libtrace_ether etc structures

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