source: lib/libtrace.h @ 3d4d52d

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 3d4d52d was 3d4d52d, checked in by Perry Lorier <perry@…>, 16 years ago

Abstract away opening up traces into a single trace_open_trace that's more
simple and reliable.

  • Property mode set to 100644
File size: 28.7 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#  define PACKED __attribute__((packed))
74#else
75#  define SIMPLE_FUNCTION
76#  define UNUSED
77#endif
78       
79/** Opaque structure holding information about an output trace */
80typedef struct libtrace_out_t libtrace_out_t;
81       
82/** Opaque structure holding information about a trace */
83typedef struct libtrace_t libtrace_t;
84       
85/** Opaque structure holding information about a bpf filter */
86typedef struct libtrace_filter_t libtrace_filter_t;
87
88typedef enum {PACKET, EXTERNAL } buf_control_t;
89/** Structure holding information about a packet */
90#define LIBTRACE_PACKET_BUFSIZE 65536
91typedef struct libtrace_packet_t {
92        struct libtrace_t *trace;
93        void *header;
94        void *payload;
95        void *buffer;
96        size_t size;
97        uint8_t type;           /* rt protocol type for the packet */
98        buf_control_t buf_control; 
99} libtrace_packet_t;
100                     
101
102/** Enumeration of error codes */
103enum {
104        TRACE_ERR_NOERROR       = 0,
105        TRACE_ERR_BAD_FORMAT    = -1,
106        TRACE_ERR_NO_INIT       = -2,
107        TRACE_ERR_NO_INIT_OUT   = -3,
108        TRACE_ERR_URI_LONG      = -4,
109        TRACE_ERR_URI_NOCOLON   = -5,
110        TRACE_ERR_INIT_FAILED   = -6,
111        TRACE_ERR_UNKNOWN_OPTION= -7,
112        TRACE_ERR_NO_CONVERSION = -8,
113        TRACE_ERR_BAD_PACKET    = -9,
114        TRACE_ERR_OPTION_UNAVAIL= -10
115};
116
117/** @name Packet structures
118 * These convenience structures are here as they are portable ways of dealing
119 * with various protocols.
120 * @{
121 */
122
123/** Structure for dealing with IP packets */
124typedef PACKED struct libtrace_ip
125{
126#if BYTE_ORDER == LITTLE_ENDIAN
127    unsigned int ip_hl:4;               /**< header length */
128    unsigned int ip_v:4;                /**< version */
129#elif BYTE_ORDER == BIG_ENDIAN
130    unsigned int ip_v:4;                /**< version */
131    unsigned int ip_hl:4;               /**< header length */
132#else
133#   error "Adjust your <bits/endian.h> defines"
134#endif
135    u_int8_t ip_tos;                    /**< type of service */
136    u_short ip_len;                     /**< total length */
137    u_short ip_id;                      /**< identification */
138#if BYTE_ORDER == LITTLE_ENDIAN
139    unsigned int ip_off:12;             /**< fragment offset */
140    unsigned int ip_mf:1;               /**< more fragments flag */
141    unsigned int ip_df:1;               /**< dont fragment flag */
142    unsigned int ip_rf:1;               /**< reserved fragment flag */
143#elif BYTE_ORDER == BIG_ENDIAN
144    unsigned int ip_rf:1;
145    unsigned int ip_df:1;
146    unsigned int ip_mf:1;
147    unsigned int ip_off:12;
148#else
149#   error "Adjust your <bits/endian.h> defines"
150#endif
151    u_int8_t ip_ttl;                    /**< time to live */
152    u_int8_t ip_p;                      /**< protocol */
153    u_short ip_sum;                     /**< checksum */
154    struct in_addr ip_src;              /**< source address */
155    struct in_addr ip_dst;              /**< dest address */
156} libtrace_ip_t
157;
158
159/** Structure for dealing with TCP packets */
160typedef struct libtrace_tcp
161  {
162    u_int16_t source;           /**< Source Port */
163    u_int16_t dest;             /**< Destination port */
164    u_int32_t seq;              /**< Sequence number */
165    u_int32_t ack_seq;          /**< Acknowledgement Number */
166#  if BYTE_ORDER == LITTLE_ENDIAN
167    unsigned int res1:4;        /**< Reserved bits */
168    unsigned int doff:4;        /**< data offset */     
169    unsigned int fin:1;         /**< FIN */
170    unsigned int syn:1;         /**< SYN flag */
171    unsigned int rst:1;         /**< RST flag */
172    unsigned int psh:1;         /**< PuSH flag */
173    unsigned int ack:1;         /**< ACK flag */
174    unsigned int urg:1;         /**< URG flag */
175    unsigned int res2:2;        /**< Reserved */
176#  elif BYTE_ORDER == BIG_ENDIAN
177    unsigned int doff:4;        /**< Data offset */
178    unsigned int res1:4;        /**< Reserved bits */
179    unsigned int res2:2;        /**< Reserved */
180    unsigned int urg:1;         /**< URG flag */
181    unsigned int ack:1;         /**< ACK flag */
182    unsigned int psh:1;         /**< PuSH flag */
183    unsigned int rst:1;         /**< RST flag */
184    unsigned int syn:1;         /**< SYN flag */
185    unsigned int fin:1;         /**< FIN flag */
186#  else
187#   error "Adjust your <bits/endian.h> defines"
188#  endif
189    u_int16_t window;           /**< Window Size */
190    u_int16_t check;            /**< Checksum */
191    u_int16_t urg_ptr;          /**< Urgent Pointer */
192} __attribute__ ((packed)) libtrace_tcp_t;
193
194/** UDP Header for dealing with UDP packets */
195typedef struct libtrace_udp {
196  u_int16_t     source;         /**< Source port */
197  u_int16_t     dest;           /**< Destination port */
198  u_int16_t     len;            /**< Length */
199  u_int16_t     check;          /**< Checksum */
200} __attribute__ ((packed)) libtrace_udp_t;
201
202/** ICMP Header for dealing with icmp packets */
203typedef struct libtrace_icmp
204{
205  u_int8_t type;                /**< message type */
206  u_int8_t code;                /**< type sub-code */
207  u_int16_t checksum;           /**< checksum */
208  union
209  {
210    struct
211    {
212      u_int16_t id;
213      u_int16_t sequence;
214    } echo;                     /**< echo datagram */
215    u_int32_t   gateway;        /**< gateway address */
216    struct
217    {
218      u_int16_t unused;
219      u_int16_t mtu;
220    } frag;                     /**< path mtu discovery */
221  } un;                         /**< Union for payloads of various icmp codes */
222} __attribute__ ((packed)) libtrace_icmp_t;
223
224/** LLC/SNAP header */
225typedef struct libtrace_llcsnap
226{
227  u_int8_t dsap;
228  u_int8_t ssap;
229  u_int8_t control;
230  u_int32_t oui:24;
231  u_int16_t type;
232} __attribute__ ((packed)) libtrace_llcsnap_t;
233
234/** 802.3 frame */
235typedef struct libtrace_ether
236{
237  u_int8_t ether_dhost[6];      /* destination ether addr */
238  u_int8_t ether_shost[6];      /* source ether addr */
239  u_int16_t ether_type;         /* packet type ID field (next-header) */
240} __attribute__ ((packed)) libtrace_ether_t;
241
242/** 802.1Q frame */
243typedef struct libtrace_8021q
244{
245  u_int8_t  ether_dhost[6];      /* destination eth addr */
246  u_int8_t  ether_shost[6];      /* source ether addr    */
247  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
248  unsigned int vlan_pri:3;       /* vlan user priority */
249  unsigned int vlan_cfi:1;       /* vlan format indicator, 0 for ethernet, 1 for token ring */
250  unsigned int vlan_id:12;       /* vlan id */
251  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
252} __attribute__ ((packed)) libtrace_8021q_t;
253
254/** ATM cell */
255typedef struct libtrace_atm_cell
256{
257  unsigned int gfc:4;
258  u_int8_t vpi;
259  u_int16_t vci;
260  unsigned int pt:3;
261  unsigned int clp:1;
262  unsigned int hec;
263} __attribute__ ((packed)) libtrace_atm_cell;
264
265/** POS header */
266typedef struct libtrace_pos
267{
268 u_int16_t header;
269 u_int16_t ether_type;
270} __attribute__ ((packed)) libtrace_pos;
271/*@}*/
272
273/** Prints help information for libtrace
274 *
275 * Function prints out some basic help information regarding libtrace,
276 * and then prints out the help() function registered with each input module
277 */
278void trace_help();
279
280/** Gets the output format for a given output trace
281 *
282 * @param libtrace      the output trace to get the name of the format fo
283 * @return callee-owned null-terminated char* containing the output format
284 *
285 */
286SIMPLE_FUNCTION
287char *trace_get_output_format(const libtrace_out_t *libtrace);
288
289/** @name Creation and destruction of traces
290 * These members deal with creating, configuring and cleaning up a trace object
291 *@{
292 */
293
294/** Create a trace file from a URI
295 *
296 * @param uri containing a valid libtrace URI
297 * @return opaque pointer to a libtrace_t
298 *
299 * Valid URI's are:
300 *  - erf:/path/to/erf/file
301 *  - erf:/path/to/erf/file.gz
302 *  - erf:/path/to/rtclient/socket
303 *  - erf:-  (stdin)
304 *  - dag:/dev/dagcard                 
305 *  - pcapint:pcapinterface                (eg: pcap:eth0)
306 *  - pcap:/path/to/pcap/file
307 *  - pcap:-
308 *  - rtclient:hostname
309 *  - rtclient:hostname:port
310 *  - wag:-
311 *  - wag:/path/to/wag/file
312 *  - wag:/path/to/wag/file.gz
313 *  - wag:/path/to/wag/socket
314 *
315 *  If an error occured when attempting to open the trace file, NULL is returned
316 *  and trace_errno is set. Use trace_perror() to get more information. 
317 *  The trace is created in the configuration state, you must call trace_start
318 *  to start the capture.
319 */
320struct libtrace_t *trace_create(const char *uri);
321
322/** Creates a "dummy" trace file that has only the format type set.
323 *
324 * @return opaque pointer to a (sparsely initialised) libtrace_t
325 *
326 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
327 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
328 * that are not associated with a libtrace_t structure.
329 */
330struct libtrace_t *trace_create_dead(const char *uri);
331
332/** Creates a trace output file from a URI.
333 *
334 * @param uri   the uri string describing the output format and destination
335 * @return opaque pointer to a libtrace_output_t
336 * @author Shane Alcock
337 *
338 * Valid URI's are:
339 *  - gzerf:/path/to/erf/file.gz
340 *  - gzerf:/path/to/erf/file
341 *  - rtserver:hostname
342 *  - rtserver:hostname:port
343 *
344 *  If an error occured when attempting to open the output trace, NULL is returned
345 *  and trace_errno is set. Use trace_perror() to get more information
346 */
347libtrace_out_t *trace_create_output(const char *uri);
348
349/** Start the capture
350 * @param libtrace      The trace to start
351 * @return 0 on success
352 *
353 * This does the actual work with starting the trace capture, and applying
354 * all the config options.  This may fail.
355 */
356int trace_start(libtrace_t *libtrace);
357
358/** Pause the capture
359 * @param libtrace      The trace to pause
360 * @return 0 on success
361 *
362 * This stops a capture in progress and returns you to the configuration
363 * state.  Any packets that arrive after trace_pause() has been called
364 * will be discarded.  To resume capture, call trace_start().
365 */
366int trace_pause(libtrace_t *libtrace);
367
368/** Start an output trace
369 * @param libtrace      The trace to start
370 * @return 0 on success
371 *
372 * This does the actual work with starting a trace for write.  This generally
373 * creates the file.
374 */
375int trace_start_output(libtrace_out_t *libtrace);
376
377/** Valid trace capture options */
378typedef enum {
379        TRACE_OPTION_SNAPLEN, /**< Number of bytes captured */
380        TRACE_OPTION_PROMISC, /**< Capture packets to other hosts */
381        TRACE_OPTION_FILTER   /**< Apply this filter to all packets recieved */
382} trace_option_t;
383
384/** Sets an input config option
385 * @param libtrace      the trace object to apply the option to
386 * @param option        the option to set
387 * @param value         the value to set the option to
388 * @return -1 if option configuration failed, 0 otherwise
389 * This should be called after trace_create, and before trace_start
390 */
391int trace_config(libtrace_t *libtrace,
392                trace_option_t option,
393                void *value);
394
395typedef enum {
396        TRACE_OPTION_OUTPUT_FILEFLAGS, /**< File flags to open the trace file
397                                        * with.  eg O_APPEND
398                                        */
399        TRACE_OPTION_OUTPUT_COMPRESS   /**< Compression level, eg 6. */
400} trace_option_output_t;
401
402/** Sets an output config option
403 *
404 * @param libtrace      the output trace object to apply the option to
405 * @param option        the option to set
406 * @param value         the value to set the option to
407 * @return -1 if option configuration failed, 0 otherwise
408 * This should be called after trace_create_output, and before
409 * trace_start_output
410 */
411int trace_config_output(libtrace_out_t *libtrace, 
412                trace_option_output_t option,
413                void *value
414                );
415
416/** Close a trace file, freeing up any resources it may have been using
417 *
418 */
419void trace_destroy(libtrace_t *trace);
420
421/** Close a trace file, freeing up any resources it may have been using
422 * @param trace         trace file to be destroyed
423 */
424void trace_destroy_dead(libtrace_t *trace);
425
426/** Close a trace output file, freeing up any resources it may have been using
427 *
428 * @param trace         the output trace file to be destroyed
429 *
430 * @author Shane Alcock
431 */
432void trace_destroy_output(libtrace_out_t *trace);
433
434/*@}*/
435
436/** @name Reading/Writing packets
437 * These members deal with creating, reading and writing packets
438 *
439 * @{
440 */
441
442/** Create a new packet object
443 *
444 * @return a pointer to an initialised libtrace_packet_t object
445 */
446libtrace_packet_t *trace_create_packet();
447
448/** Destroy a packet object
449 *
450 * sideeffect: sets packet to NULL
451 */
452void trace_destroy_packet(libtrace_packet_t **packet);
453
454
455/** Read one packet from the trace into buffer
456 *
457 * @param trace         the libtrace opaque pointer
458 * @param packet        the packet opaque pointer
459 * @return 0 on EOF, negative value on error
460 *
461 * @note the trace must have been started with trace_start before calling
462 * this function
463 */
464int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet);
465
466/** Event types
467 * see \ref libtrace_eventobj_t and \ref trace_event
468 */
469typedef enum {
470        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
471        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
472        TRACE_EVENT_PACKET,     /**< packet has arrived */
473        TRACE_EVENT_TERMINATE   /**< End of trace */
474} libtrace_event_t;
475
476/** structure returned by libtrace_event explaining what the current event is */
477typedef struct libtrace_eventobj_t {
478        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
479        int fd;                /**< if IOWAIT, the fd to sleep on */
480        double seconds;        /**< if SLEEP, the amount of time to sleep for */
481        int size;              /**< if PACKET, the value returned from trace_read_packet */
482} libtrace_eventobj_t;
483
484/** process a libtrace event
485 * @param trace the libtrace opaque pointer
486 * @param packet the libtrace_packet opaque pointer
487 * @return libtrace_event struct containing the type, and potential
488 *      fd or seconds to sleep on
489 *
490 * Type can be:
491 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
492 *  TRACE_EVENT_SLEEP   Next event in seconds
493 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
494 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
495 */
496libtrace_eventobj_t trace_event(libtrace_t *trace,
497                libtrace_packet_t *packet);
498
499
500/** Write one packet out to the output trace
501 *
502 * @param trace         the libtrace_out opaque pointer
503 * @param packet        the packet opaque pointer
504 * @return the number of bytes written out, if zero or negative then an error has occured.
505 */
506int trace_write_packet(libtrace_out_t *trace, const libtrace_packet_t *packet);
507/*@}*/
508
509/** @name Headers
510 * These functions locate and return a pointer to various headers inside a packet
511 * @{
512 */
513
514/** get a pointer to the link layer
515 * @param packet        the packet opaque pointer
516 *
517 * @return a pointer to the link layer, or NULL if there is no link layer
518 *
519 * @note you should call getLinkType() to find out what type of link layer
520 * this is
521 */
522SIMPLE_FUNCTION
523void *trace_get_link(const libtrace_packet_t *packet);
524
525/** get a pointer to the IP header (if any)
526 * @param packet        the packet opaque pointer
527 *
528 * @return a pointer to the IP header, or NULL if there is not an IP packet
529 */
530SIMPLE_FUNCTION
531libtrace_ip_t *trace_get_ip(const libtrace_packet_t *packet);
532
533/** Gets a pointer to the transport layer header (if any)
534 * @param packet        a pointer to a libtrace_packet structure
535 *
536 * @return a pointer to the transport layer header, or NULL if there is no header
537 */
538void *trace_get_transport(const libtrace_packet_t *packet);
539
540/** Gets a pointer to the transport layer header (if any) given a pointer to the
541 * IP header
542 * @param ip            The IP Header
543 * @param[out] skipped  An output variable of the number of bytes skipped
544 *
545 * @return a pointer to the transport layer header, or NULL if there is no header
546 *
547 * Skipped can be NULL, in which case it will be ignored
548 */
549void *trace_get_transport_from_ip(const libtrace_ip_t *ip, int *skipped);
550
551/** get a pointer to the TCP header (if any)
552 * @param packet        the packet opaque pointer
553 *
554 * @return a pointer to the TCP header, or NULL if there is not a TCP packet
555 */
556SIMPLE_FUNCTION
557libtrace_tcp_t *trace_get_tcp(const libtrace_packet_t *packet);
558
559/** get a pointer to the TCP header (if any) given a pointer to the IP header
560 * @param ip            The IP header
561 * @param[out] skipped  An output variable of the number of bytes skipped
562 *
563 * @return a pointer to the TCP header, or NULL if this is not a TCP packet
564 *
565 * Skipped can be NULL, in which case it will be ignored by the program.
566 *
567 * @author Perry Lorier
568 */
569SIMPLE_FUNCTION
570libtrace_tcp_t *trace_get_tcp_from_ip(const libtrace_ip_t *ip,int *skipped);
571
572/** get a pointer to the UDP header (if any)
573 * @param packet        the packet opaque pointer
574 *
575 * @return a pointer to the UDP header, or NULL if this is not a UDP packet
576 */
577SIMPLE_FUNCTION
578libtrace_udp_t *trace_get_udp(const libtrace_packet_t *packet);
579
580/** get a pointer to the UDP header (if any) given a pointer to the IP header
581 * @param       ip      The IP header
582 * @param[out]  skipped An output variable of the number of bytes skipped
583 *
584 * @return a pointer to the UDP header, or NULL if this is not an UDP packet
585 *
586 * Skipped may be NULL, in which case it will be ignored by this function.
587 */
588SIMPLE_FUNCTION
589libtrace_udp_t *trace_get_udp_from_ip(const libtrace_ip_t *ip,int *skipped);
590
591/** get a pointer to the ICMP header (if any)
592 * @param packet        the packet opaque pointer
593 *
594 * @return a pointer to the ICMP header, or NULL if this is not a ICMP packet
595 */
596SIMPLE_FUNCTION
597libtrace_icmp_t *trace_get_icmp(const libtrace_packet_t *packet);
598
599/** get a pointer to the ICMP header (if any) given a pointer to the IP header
600 * @param ip            The IP header
601 * @param[out] skipped  An output variable of the number of bytes skipped
602 *
603 * @return a pointer to the ICMP header, or NULL if this is not an ICMP packet
604 *
605 * Skipped may be NULL, in which case it will be ignored by this function
606 */
607SIMPLE_FUNCTION
608libtrace_icmp_t *trace_get_icmp_from_ip(const libtrace_ip_t *ip,int *skipped);
609/*@}*/
610
611/** parse an ip or tcp option
612 * @param[in,out] ptr   the pointer to the current option
613 * @param[in,out] len   the length of the remaining buffer
614 * @param[out] type     the type of the option
615 * @param[out] optlen   the length of the option
616 * @param[out] data     the data of the option
617 *
618 * @return bool true if there is another option (and the fields are filled in)
619 *               or false if this was the last option.
620 *
621 * This updates ptr to point to the next option after this one, and updates
622 * len to be the number of bytes remaining in the options area.  Type is updated
623 * to be the code of this option, and data points to the data of this option,
624 * with optlen saying how many bytes there are.
625 *
626 * @note Beware of fragmented packets.
627 */
628int trace_get_next_option(unsigned char **ptr,int *len,
629                        unsigned char *type,
630                        unsigned char *optlen,
631                        unsigned char **data);
632
633
634/** @name Time
635 * These functions deal with time that a packet arrived and return it
636 * in various formats
637 * @{
638 */
639/** Get the current time in DAG time format
640 * @param packet        the packet opaque pointer
641 *
642 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
643 * past 1970-01-01, the lower 32bits are partial seconds)
644 * @author Daniel Lawson
645 */
646SIMPLE_FUNCTION
647uint64_t trace_get_erf_timestamp(const libtrace_packet_t *packet);
648
649/** Get the current time in struct timeval
650 * @param packet        the packet opaque pointer
651 *
652 * @return time that this packet was seen in a struct timeval
653 * @author Daniel Lawson
654 * @author Perry Lorier
655 */ 
656SIMPLE_FUNCTION
657struct timeval trace_get_timeval(const libtrace_packet_t *packet);
658
659/** Get the current time in floating point seconds
660 * @param packet        the packet opaque pointer
661 *
662 * @return time that this packet was seen in 64bit floating point seconds
663 * @author Daniel Lawson
664 * @author Perry Lorier
665 */
666SIMPLE_FUNCTION
667double trace_get_seconds(const libtrace_packet_t *packet);
668/*@}*/
669
670/** @name Sizes
671 * This section deals with finding or setting the various different lengths
672 * a packet can have
673 * @{
674 */
675/** Get the size of the packet in the trace
676 * @param packet        the packet opaque pointer
677 * @return the size of the packet in the trace
678 * @author Perry Lorier
679 * @note Due to this being a header capture, or anonymisation, this may not
680 * be the same size as the original packet.  See get_wire_length() for the original
681 * size of the packet.
682 * @note This can (and often is) different for different packets in a trace!
683 * @par
684 *  This is sometimes called the "snaplen".
685 */
686SIMPLE_FUNCTION
687int trace_get_capture_length(const libtrace_packet_t *packet);
688
689/** Get the size of the packet as it was seen on the wire.
690 * @param packet        the packet opaque pointer
691 * @return the size of the packet as it was on the wire.
692 * @author Perry Lorier
693 * @author Daniel Lawson
694 * @note Due to the trace being a header capture, or anonymisation this may
695 * not be the same as the Capture Len.
696 */ 
697SIMPLE_FUNCTION
698int trace_get_wire_length(const libtrace_packet_t *packet);
699
700/** Get the length of the capture framing headers.
701 * @param packet        the packet opaque pointer
702 * @return the size of the packet as it was on the wire.
703 * @author Perry Lorier
704 * @author Daniel Lawson
705 * @note this length corresponds to the difference between the size of a
706 * captured packet in memory, and the captured length of the packet
707 */ 
708SIMPLE_FUNCTION
709int trace_get_framing_length(const libtrace_packet_t *packet);
710
711/** Truncate the packet at the suggested length
712 * @param packet        the packet opaque pointer
713 * @param size          the new length of the packet
714 * @return the new length of the packet, or the original length of the
715 * packet if unchanged
716 * @author Daniel Lawson
717 */
718size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
719
720/** Seek within a trace
721 * @param trace         trace to seek
722 * @param seconds       time to seek to
723 * @return 0 on success.
724 * Make the next packet read to be the first packet to occur at or after the
725 * time searched for.  This must be called in the configuration state (ie,
726 * before trace_start() or after trace_pause().
727 * @note This function may be extremely slow.
728 */
729int trace_seek_seconds(libtrace_t *trace, double seconds);
730
731/** Seek within a trace
732 * @param trace         trace to seek
733 * @param tv            time to seek to
734 * @return 0 on success.
735 * Make the next packet read to be the first packet to occur at or after the
736 * time searched for.  This must be called in the configuration state (ie,
737 * before trace_start() or after trace_pause().
738 * @note This function may be extremely slow.
739 */
740int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
741
742/*@}*/
743
744
745/** Link layer types
746 * This enumates the various different link types that libtrace understands
747 */
748typedef enum { 
749       TRACE_TYPE_LEGACY,       
750       TRACE_TYPE_HDLC_POS, 
751       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
752       TRACE_TYPE_ATM,
753       TRACE_TYPE_80211,                /**< 802.11 frames */
754       TRACE_TYPE_NONE,
755       TRACE_TYPE_LINUX_SLL,            /**< Linux "null" framing */
756       TRACE_TYPE_PFLOG,                /**< FreeBSD's PFlug */
757       TRACE_TYPE_LEGACY_DEFAULT,
758       TRACE_TYPE_LEGACY_POS,
759       TRACE_TYPE_LEGACY_ATM,
760       TRACE_TYPE_LEGACY_ETH,
761       TRACE_TYPE_80211_PRISM
762     } libtrace_linktype_t;
763
764/** Get the type of the link layer
765 * @param packet        the packet opaque pointer
766 * @return libtrace_linktype_t
767 * @author Perry Lorier
768 * @author Daniel Lawson
769 */
770SIMPLE_FUNCTION
771inline libtrace_linktype_t trace_get_link_type(const libtrace_packet_t *packet);
772
773/** Get the destination MAC addres
774 * @param packet        the packet opaque pointer
775 * @return a pointer to the destination mac, (or NULL if there is no
776 * destination MAC)
777 * @author Perry Lorier
778 */
779SIMPLE_FUNCTION
780uint8_t *trace_get_destination_mac(const libtrace_packet_t *packet);
781
782/** Get the source MAC addres
783 * @param packet        the packet opaque pointer
784 * @return a pointer to the source mac, (or NULL if there is no source MAC)
785 * @author Perry Lorier
786 */
787SIMPLE_FUNCTION
788uint8_t *trace_get_source_mac(const libtrace_packet_t *packet);
789
790/** Set the direction flag, if it has one
791 * @param packet        the packet opaque pointer
792 * @param direction     the new direction (0,1,2,3)
793 * @return a signed value containing the direction flag, or -1 if this is not supported
794 * @author Daniel Lawson
795 */
796int8_t trace_set_direction(libtrace_packet_t *packet, int8_t direction);
797
798/** Get the direction flag, if it has one
799 * @param packet        the packet opaque pointer
800 * @return a signed value containing the direction flag, or -1 if this is not supported
801 * The direction is defined as 0 for packets originating locally (ie, outbound)
802 * and 1 for packets originating remotely (ie, inbound).
803 * Other values are possible, which might be overloaded to mean special things
804 * for a special trace.
805 * @author Daniel Lawson
806 */
807SIMPLE_FUNCTION
808int8_t trace_get_direction(const libtrace_packet_t *packet);
809
810/** @name BPF
811 * This section deals with using Berkley Packet Filters
812 * @{
813 */
814/** setup a BPF filter
815 * @param filterstring a char * containing the bpf filter string
816 * @return opaque pointer pointer to a libtrace_filter_t object
817 * @author Daniel Lawson
818 * @note The filter is not actually compiled at this point, so no correctness
819 * tests are performed here. trace_bpf_setfilter will always return ok, but
820 * if the filter is poorly constructed an error will be generated when the
821 * filter is actually used
822 */
823SIMPLE_FUNCTION
824libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
825
826/** apply a BPF filter
827 * @param filter        the filter opaque pointer
828 * @param packet        the packet opaque pointer
829 * @return 0 if the filter fails, 1 if it succeeds
830 * @author Daniel Lawson
831 * @note Due to the way BPF filters are built, the filter is not actually compiled
832 * 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.
833 */
834int trace_bpf_filter(libtrace_filter_t *filter,
835                const libtrace_packet_t *packet);
836/*@}*/
837
838/** Which port is the server port */
839typedef enum {
840        USE_DEST,       /**< Destination port is the server port */
841        USE_SOURCE      /**< Source port is the server port */
842} serverport_t;
843
844/** Get the source port
845 * @param packet        the packet to read from
846 * @return a port in \em HOST byte order, or equivilent to ports for this
847 * protocol, or 0 if this protocol has no ports.
848 * @author Perry Lorier
849 */
850SIMPLE_FUNCTION
851uint16_t trace_get_source_port(const libtrace_packet_t *packet);
852
853/** Get the destination port
854 * @param packet        the packet to read from
855 * @return a port in \em HOST byte order, or equivilent to ports for this
856 * protocol, or 0 if this protocol has no ports.
857 * @author Perry Lorier
858 */
859SIMPLE_FUNCTION
860uint16_t trace_get_destination_port(const libtrace_packet_t *packet);
861
862/** hint at the server port in specified protocol
863 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
864 * @param source        the source port from the packet
865 * @param dest          the destination port from the packet
866 * @return one of USE_SOURCE or USE_DEST depending on which one you should use
867 * @note ports must be in \em HOST byte order!
868 * @author Daniel Lawson
869 */
870SIMPLE_FUNCTION
871int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
872
873/** Takes a uri and splits it into a format and uridata component.
874 * Primarily for internal use but made available for external use.
875 * @param uri           the uri to be parsed
876 * @param format        destination location for the format component of the uri
877 * @return 0 if an error occured, otherwise return the uridata component
878 * @author Shane Alcock
879 */
880const char *trace_parse_uri(const char *uri, char **format);
881
882/** libtrace error information */
883extern struct trace_err_t{
884        int err_num;            /**< error code */
885        char problem[255];      /**< the format, uri etc that caused the error for reporting purposes */
886} trace_err;
887#ifdef __cplusplus
888} /* extern "C" */
889#endif /* #ifdef __cplusplus */
890#endif /* LIBTRACE_H_ */
Note: See TracBrowser for help on using the repository browser.