source: lib/libtrace.h @ 5b91b48

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 5b91b48 was 0a6638f, checked in by Perry Lorier <perry@…>, 15 years ago

Fixed up erf output
Force trace_create_packet to be called, don't let people cheat.

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