source: lib/libtrace.h @ 7068467

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

Major cleanup of libtrace3
Lots of documentation fixes
Lots of zerocopy fixes
Lots of config option fixes

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