source: lib/libtrace.h @ 1fbd938

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

More -pedantic cleanups
Changed the format structure (again) for pause and seek support

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