source: lib/libtrace.h @ 0ea3526

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

Add new error handling

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