source: lib/libtrace.h @ 3b8a5ef

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 3b8a5ef was 3b8a5ef, checked in by Daniel Lawson <dlawson@…>, 16 years ago

I hate shane

  • Property mode set to 100644
File size: 24.4 KB
RevLine 
[a79ddbe]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
[2137b49]31#ifndef LIBTRACE_H
32#define LIBTRACE_H
[27615e9]33
[2c060e3]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
[fba4ca0]48 * See the example/ directory in the source distribution for some simple examples
[2c060e3]49 * @par Linking
[90e4aa4]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
[d95447b]54 * Woody, at least, does not support large file offsets.
[2c060e3]55 *
56 */
57
[803ea87]58#include <sys/types.h>
59#include <netinet/in.h>
60/** API version as 2 byte hex digits, eg 0xXXYYZZ */
[3b8a5ef]61#define LIBTRACE_API_VERSION 0x030000  /* 3.0.00 */
[803ea87]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))
[3b8a5ef]72#  define UNUSED __attribute__((unused))
[803ea87]73#else
74#  define SIMPLE_FUNCTION
[3b8a5ef]75#  define UNUSED
[803ea87]76#endif
77       
78#define RT_DATA 1
79#define RT_MSG 2
[2c060e3]80
[a114d8b5]81       
[5eae97a]82/** Opaque structure holding information about an output trace */
[5a67294]83typedef struct libtrace_out_t libtrace_out_t;
[5eae97a]84       
[2c060e3]85/** Opaque structure holding information about a trace */
[5a67294]86typedef struct libtrace_t libtrace_t;
[2c060e3]87       
[c5a22ec]88/** Opaque structure holding information about a bpf filter */
[5a67294]89typedef struct libtrace_filter_t libtrace_filter_t;
[2137b49]90
[9cecdb2]91/** Structure holding status information for a packet */
92typedef struct libtrace_packet_status {
93        uint8_t type;
94        uint8_t reserved;
95        uint16_t message;
96
97} libtrace_packet_status_t;
98
[14d8a63]99typedef enum {PACKET, EXTERNAL } buf_control_t;
[8283f05]100/** Structure holding information about a packet */
101#define LIBTRACE_PACKET_BUFSIZE 65536
[5a67294]102typedef struct libtrace_packet_t {
[14d8a63]103        struct libtrace_t *trace;
104        void *header;
105        void *payload;
106        void *buffer;
[8283f05]107        size_t size;
[9cecdb2]108        libtrace_packet_status_t status;
[14d8a63]109        buf_control_t buf_control; 
[5a67294]110} __attribute__ ((packed)) libtrace_packet_t;
[8283f05]111                     
[2137b49]112
[ffc8c8d]113/** Enumeration of error codes */
114enum {E_NOERROR, E_BAD_FORMAT, E_NO_INIT, E_NO_INIT_OUT, E_URI_LONG, E_URI_NOCOLON, E_INIT_FAILED };
115
[2c060e3]116/** Structure for dealing with IP packets */
[5a67294]117typedef struct libtrace_ip
[fba4ca0]118{
[568dc0e]119#if BYTE_ORDER == LITTLE_ENDIAN
[2c060e3]120    unsigned int ip_hl:4;               /**< header length */
121    unsigned int ip_v:4;                /**< version */
[568dc0e]122#elif BYTE_ORDER == BIG_ENDIAN
[2c060e3]123    unsigned int ip_v:4;                /**< version */
124    unsigned int ip_hl:4;               /**< header length */
[568dc0e]125#else
126#   error "Adjust your <bits/endian.h> defines"
[2c060e3]127#endif
128    u_int8_t ip_tos;                    /**< type of service */
129    u_short ip_len;                     /**< total length */
130    u_short ip_id;                      /**< identification */
131    u_short ip_off;                     /**< fragment offset field */
132#define IP_RF 0x8000                    /**< reserved fragment flag */
133#define IP_DF 0x4000                    /**< dont fragment flag */
134#define IP_MF 0x2000                    /**< more fragments flag */
135#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
136    u_int8_t ip_ttl;                    /**< time to live */
137    u_int8_t ip_p;                      /**< protocol */
138    u_short ip_sum;                     /**< checksum */
[10814d7]139    struct in_addr ip_src;              /**< source address */
140    struct in_addr ip_dst;              /**< dest address */
[5a67294]141} __attribute__ ((packed)) libtrace_ip_t
142;
[2c060e3]143
144/** Structure for dealing with TCP packets */
[5a67294]145typedef struct libtrace_tcp
[2c060e3]146  {
147    u_int16_t source;           /**< Source Port */
148    u_int16_t dest;             /**< Destination port */
149    u_int32_t seq;              /**< Sequence number */
150    u_int32_t ack_seq;          /**< Acknowledgement Number */
[568dc0e]151#  if BYTE_ORDER == LITTLE_ENDIAN
[2c060e3]152    u_int16_t res1:4;           /**< Reserved bits */
153    u_int16_t doff:4;           
154    u_int16_t fin:1;            /**< FIN */
155    u_int16_t syn:1;            /**< SYN flag */
156    u_int16_t rst:1;            /**< RST flag */
157    u_int16_t psh:1;            /**< PuSH flag */
158    u_int16_t ack:1;            /**< ACK flag */
159    u_int16_t urg:1;            /**< URG flag */
160    u_int16_t res2:2;           /**< Reserved */
[568dc0e]161#  elif BYTE_ORDER == BIG_ENDIAN
[2c060e3]162    u_int16_t doff:4;           
[d95447b]163    u_int16_t res1:4;           /**< Reserved bits */
164    u_int16_t res2:2;           /**< Reserved */
165    u_int16_t urg:1;            /**< URG flag */
166    u_int16_t ack:1;            /**< ACK flag */
167    u_int16_t psh:1;            /**< PuSH flag */
168    u_int16_t rst:1;            /**< RST flag */
169    u_int16_t syn:1;            /**< SYN flag */
170    u_int16_t fin:1;            /**< FIN flag */
[2c060e3]171#  else
172#   error "Adjust your <bits/endian.h> defines"
173#  endif
174    u_int16_t window;           /**< Window Size */
175    u_int16_t check;            /**< Checksum */
176    u_int16_t urg_ptr;          /**< Urgent Pointer */
[5a67294]177} __attribute__ ((packed)) libtrace_tcp_t;
[2c060e3]178
179/** UDP Header for dealing with UDP packets */
[5a67294]180typedef struct libtrace_udp {
[2c060e3]181  u_int16_t     source;         /**< Source port */
182  u_int16_t     dest;           /**< Destination port */
183  u_int16_t     len;            /**< Length */
184  u_int16_t     check;          /**< Checksum */
[5a67294]185} __attribute__ ((packed)) libtrace_udp_t;
[2c060e3]186
187/** ICMP Header for dealing with icmp packets */
[5a67294]188typedef struct libtrace_icmp
[2c060e3]189{
[d95447b]190  u_int8_t type;                /**< message type */
191  u_int8_t code;                /**< type sub-code */
192  u_int16_t checksum;           /**< checksum */
[2c060e3]193  union
194  {
195    struct
196    {
197      u_int16_t id;
198      u_int16_t sequence;
[d95447b]199    } echo;                     /**< echo datagram */
200    u_int32_t   gateway;        /**< gateway address */
[2c060e3]201    struct
202    {
[5c5b47b]203      u_int16_t unused;
[2c060e3]204      u_int16_t mtu;
[d95447b]205    } frag;                     /**< path mtu discovery */
[31709e8d]206  } un;                         /**< Union for payloads of various icmp codes */
[5a67294]207} __attribute__ ((packed)) libtrace_icmp_t;
[fba4ca0]208
[3b8a5ef]209/** LLC/SNAP header */
210typedef struct libtrace_llcsnap
211{
212  u_int8_t dsap;
213  u_int8_t ssap;
214  u_int8_t control;
215  u_int32_t oui:24;
216  u_int16_t type;
217} __attribute__ ((packed)) libtrace_llcsnap_t;
218
[fba4ca0]219/** 802.3 frame */
[3b8338b]220typedef struct libtrace_ether
[fba4ca0]221{
222  u_int8_t ether_dhost[6];      /* destination ether addr */
223  u_int8_t ether_shost[6];      /* source ether addr */
224  u_int16_t ether_type;         /* packet type ID field (next-header) */
[5a67294]225} __attribute__ ((packed)) libtrace_ether_t;
[2c060e3]226
[5bbe424]227/** 802.1Q frame */
[3b8338b]228typedef struct libtrace_8021q
[5bbe424]229{
230  u_int8_t  ether_dhost[6];      /* destination eth addr */
231  u_int8_t  ether_shost[6];      /* source ether addr    */
[fba4ca0]232  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
233  u_int16_t vlan_pri:3;          /* vlan user priority */
234  u_int16_t vlan_cfi:1;          /* vlan format indicator, 0 for ethernet, 1 for token ring */
235  u_int16_t vlan_id:12;          /* vlan id */
236  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
[5a67294]237} __attribute__ ((packed)) libtrace_8021q_t;
[2c060e3]238
[f04e489]239/** ATM cell */
[5a67294]240typedef struct libtrace_atm_cell
[f04e489]241{
242  u_int8_t gfc:4;
243  u_int8_t vpi;
244  u_int16_t vci;
245  u_int8_t pt:3;
246  u_int8_t clp:1;
247  u_int8_t hec;
[5a67294]248} __attribute__ ((packed)) libtrace_atm_cell;
[f04e489]249
250/** POS header */
[5a67294]251typedef struct libtrace_pos
[f04e489]252{
253 u_int16_t header;
254 u_int16_t ether_type;
[5a67294]255} __attribute__ ((packed)) libtrace_pos;
[f04e489]256
[40ba6ad]257/** Prints help information for libtrace
258 *
259 * Function prints out some basic help information regarding libtrace,
260 * and then prints out the help() function registered with each input module
261 */
262void trace_help();
[2c060e3]263
[4d5a9a7]264/** Gets the output format for a given output trace
265 *
[31709e8d]266 * @param libtrace      the output trace to get the name of the format fo
[fba4ca0]267 * @returns callee-owned null-terminated char* containing the output format
268 *
[4d5a9a7]269 */
[31709e8d]270SIMPLE_FUNCTION
271char *trace_get_output_format(const struct libtrace_out_t *libtrace);
[4d5a9a7]272
[ffc8c8d]273/** Prints error information
274 *
275 * Prints out a descriptive error message for the currently set trace_err value
276 */
[31709e8d]277void trace_perror(const char *caller);
[2c060e3]278
279/** Create a trace file from a URI
280 *
[31709e8d]281 * @param uri containing a valid libtrace URI
[2c060e3]282 * @returns opaque pointer to a libtrace_t
283 *
284 * Valid URI's are:
285 *  - erf:/path/to/erf/file
286 *  - erf:/path/to/erf/file.gz
287 *  - erf:/path/to/rtclient/socket
288 *  - erf:-  (stdin)
[fba4ca0]289 *  - dag:/dev/dagcard                 
[fe43699]290 *  - pcapint:pcapinterface                (eg: pcap:eth0)
[2c060e3]291 *  - pcap:/path/to/pcap/file
292 *  - pcap:-
293 *  - rtclient:hostname
294 *  - rtclient:hostname:port
[fba4ca0]295 *  - wag:-
[2c060e3]296 *  - wag:/path/to/wag/file
297 *  - wag:/path/to/wag/file.gz
298 *  - wag:/path/to/wag/socket
299 *
[5eae97a]300 *  If an error occured when attempting to open the trace file, NULL is returned
[fba4ca0]301 *  and trace_errno is set. Use trace_perror() to get more information
[2c060e3]302 */
[31709e8d]303struct libtrace_t *trace_create(const char *uri);
[2c060e3]304
[084d95a]305/** Creates a "dummy" trace file that has only the format type set.
306 *
307 * @returns opaque pointer to a (sparsely initialised) libtrace_t
308 *
309 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
310 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
311 * that are not associated with a libtrace_t structure.
312 */
[31709e8d]313struct libtrace_t *trace_create_dead(const char *uri);
[084d95a]314
[5eae97a]315/** Creates a trace output file from a URI.
316 *
[fba4ca0]317 * @param uri   the uri string describing the output format and destination
[5eae97a]318 * @returns opaque pointer to a libtrace_output_t
[fba4ca0]319 * @author Shane Alcock
[5eae97a]320 *
321 * Valid URI's are:
322 *  - gzerf:/path/to/erf/file.gz
323 *  - gzerf:/path/to/erf/file
324 *  - rtserver:hostname
325 *  - rtserver:hostname:port
326 *
[fba4ca0]327 *  If an error occured when attempting to open the output trace, NULL is returned
328 *  and trace_errno is set. Use trace_perror() to get more information
[5eae97a]329 */
[31709e8d]330struct libtrace_out_t *trace_output_create(const char *uri);
[5eae97a]331
[31709e8d]332/** Parses an output options string and calls the appropriate function to deal with output options.
[f99a183]333 *
[fba4ca0]334 * @param libtrace      the output trace object to apply the options to
335 * @param options       the options string
336 * @returns -1 if option configuration failed, 0 otherwise
337 *
338 * @author Shane Alcock
[f99a183]339 */
[91ebc50]340int trace_output_config(struct libtrace_out_t *libtrace, char *options);
341
[2c060e3]342/** Close a trace file, freeing up any resources it may have been using
343 *
344 */
[2137b49]345void trace_destroy(struct libtrace_t *trace);
[2c060e3]346
[31709e8d]347/** Close a trace file, freeing up any resources it may have been using
348 * @param trace         trace file to be destroyed
349 */
[084d95a]350void trace_destroy_dead(struct libtrace_t *trace);
351
[5eae97a]352/** Close a trace output file, freeing up any resources it may have been using
353 *
[31709e8d]354 * @param trace         the output trace file to be destroyed
[fba4ca0]355 *
356 * @author Shane Alcock
[5eae97a]357 */
358void trace_output_destroy(struct libtrace_out_t *trace);
359
[14d8a63]360/** Create a new packet object
361 *
362 * @return a pointer to an initialised libtrace_packet_t object
363 */
364struct libtrace_packet_t *trace_packet_create();
365
366/** Destroy a packet object
367 *
368 * sideeffect: sets packet to NULL
369 */
370void trace_packet_destroy(struct libtrace_packet_t **packet);
371
372
[2c060e3]373/** Read one packet from the trace into buffer
374 *
[5eae97a]375 * @param trace         the libtrace opaque pointer
[2137b49]376 * @param packet        the packet opaque pointer
[fba4ca0]377 * @returns 0 on EOF, negative value on error
[2c060e3]378 *
379 */
[2137b49]380int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
[2c060e3]381
[5eae97a]382/** Write one packet out to the output trace
383 *
384 * @param trace         the libtrace_out opaque pointer
385 * @param packet        the packet opaque pointer
386 * @returns the number of bytes written out, if zero or negative then an error has occured.
387 */
[31709e8d]388int trace_write_packet(struct libtrace_out_t *trace, const struct libtrace_packet_t *packet);
[5eae97a]389
[2c060e3]390/** get a pointer to the link layer
[2137b49]391 * @param packet        the packet opaque pointer
[2c060e3]392 *
393 * @returns a pointer to the link layer, or NULL if there is no link layer
394 *
395 * @note you should call getLinkType() to find out what type of link layer
396 * this is
397 */
[31709e8d]398SIMPLE_FUNCTION
[00c1935]399void *trace_get_link(const struct libtrace_packet_t *packet);
[2c060e3]400
401/** get a pointer to the IP header (if any)
[2137b49]402 * @param packet        the packet opaque pointer
[2c060e3]403 *
404 * @returns a pointer to the IP header, or NULL if there is not an IP packet
405 */
[31709e8d]406SIMPLE_FUNCTION
[58e9e02]407struct libtrace_ip *trace_get_ip(const struct libtrace_packet_t *packet);
[2c060e3]408
409/** get a pointer to the TCP header (if any)
[2137b49]410 * @param packet        the packet opaque pointer
[2c060e3]411 *
412 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
413 */
[31709e8d]414SIMPLE_FUNCTION
[58e9e02]415struct libtrace_tcp *trace_get_tcp(const struct libtrace_packet_t *packet);
[2c060e3]416
[68667ee]417/** get a pointer to the TCP header (if any) given a pointer to the IP header
418 * @param ip            The IP header
419 * @param[out] skipped  An output variable of the number of bytes skipped
420 *
421 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
422 *
423 * Skipped can be NULL, in which case it will be ignored by the program.
424 *
425 * @author Perry Lorier
426 */
[31709e8d]427SIMPLE_FUNCTION
[5395ce6]428struct libtrace_tcp *trace_get_tcp_from_ip(const struct libtrace_ip *ip,int *skipped);
[68667ee]429
[2c060e3]430/** get a pointer to the UDP header (if any)
[2137b49]431 * @param packet        the packet opaque pointer
[2c060e3]432 *
433 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
434 */
[31709e8d]435SIMPLE_FUNCTION
[58e9e02]436struct libtrace_udp *trace_get_udp(const struct libtrace_packet_t *packet);
[2c060e3]437
[68667ee]438/** get a pointer to the UDP header (if any) given a pointer to the IP header
439 * @param       ip      The IP header
440 * @param[out]  skipped An output variable of the number of bytes skipped
441 *
442 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
443 *
444 * Skipped may be NULL, in which case it will be ignored by this function.
445 */
[31709e8d]446SIMPLE_FUNCTION
[5395ce6]447struct libtrace_udp *trace_get_udp_from_ip(const struct libtrace_ip *ip,int *skipped);
[68667ee]448
[2c060e3]449/** get a pointer to the ICMP header (if any)
[2137b49]450 * @param packet        the packet opaque pointer
[2c060e3]451 *
452 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
453 */
[31709e8d]454SIMPLE_FUNCTION
[58e9e02]455struct libtrace_icmp *trace_get_icmp(const struct libtrace_packet_t *packet);
[2c060e3]456
[68667ee]457/** get a pointer to the ICMP header (if any) given a pointer to the IP header
458 * @param ip            The IP header
459 * @param[out] skipped  An output variable of the number of bytes skipped
460 *
461 * @returns a pointer to the ICMP header, or NULL if this is not an ICMP packet
462 *
463 * Skipped may be NULL, in which case it will be ignored by this function
464 */
[31709e8d]465SIMPLE_FUNCTION
[5395ce6]466struct libtrace_icmp *trace_get_icmp_from_ip(const struct libtrace_ip *ip,int *skipped);
[68667ee]467
468/** parse an ip or tcp option
469 * @param[in,out] ptr   the pointer to the current option
470 * @param[in,out] len   the length of the remaining buffer
471 * @param[out] type     the type of the option
472 * @param[out] optlen   the length of the option
473 * @param[out] data     the data of the option
474 *
475 * @returns bool true if there is another option (and the fields are filled in)
476 *               or false if this was the last option.
477 *
478 * This updates ptr to point to the next option after this one, and updates
479 * len to be the number of bytes remaining in the options area.  Type is updated
480 * to be the code of this option, and data points to the data of this option,
481 * with optlen saying how many bytes there are.
482 *
483 * @note Beware of fragmented packets.
484 */
485int trace_get_next_option(unsigned char **ptr,int *len,
486                        unsigned char *type,
487                        unsigned char *optlen,
488                        unsigned char **data);
489
490
[2c060e3]491/** Get the current time in DAG time format
[2137b49]492 * @param packet        the packet opaque pointer
493 *
[2c060e3]494 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
495 * past 1970-01-01, the lower 32bits are partial seconds)
496 * @author Daniel Lawson
497 */
[31709e8d]498SIMPLE_FUNCTION
[68667ee]499uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
[2c060e3]500
501/** Get the current time in struct timeval
[2137b49]502 * @param packet        the packet opaque pointer
503 *
[2c060e3]504 * @returns time that this packet was seen in a struct timeval
505 * @author Daniel Lawson
506 * @author Perry Lorier
507 */ 
[31709e8d]508SIMPLE_FUNCTION
[68667ee]509struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
[2c060e3]510
511/** Get the current time in floating point seconds
[2137b49]512 * @param packet        the packet opaque pointer
513 *
[2c060e3]514 * @returns time that this packet was seen in 64bit floating point seconds
[fba4ca0]515 * @author Daniel Lawson
[2c060e3]516 * @author Perry Lorier
517 */
[31709e8d]518SIMPLE_FUNCTION
[68667ee]519double trace_get_seconds(const struct libtrace_packet_t *packet);
[2c060e3]520
521/** Get the size of the packet in the trace
[2137b49]522 * @param packet        the packet opaque pointer
[2c060e3]523 * @returns the size of the packet in the trace
524 * @author Perry Lorier
525 * @note Due to this being a header capture, or anonymisation, this may not
[c681e86]526 * be the same size as the original packet.  See get_wire_length() for the original
[2c060e3]527 * size of the packet.
528 * @note This can (and often is) different for different packets in a trace!
529 * @par
530 *  This is sometimes called the "snaplen".
531 */
[31709e8d]532SIMPLE_FUNCTION
[68667ee]533int trace_get_capture_length(const struct libtrace_packet_t *packet);
[2c060e3]534
535/** Get the size of the packet as it was seen on the wire.
[2137b49]536 * @param packet        the packet opaque pointer
[2c060e3]537 * @returns the size of the packet as it was on the wire.
538 * @author Perry Lorier
539 * @author Daniel Lawson
540 * @note Due to the trace being a header capture, or anonymisation this may
541 * not be the same as the Capture Len.
542 */ 
[31709e8d]543SIMPLE_FUNCTION
[68667ee]544int trace_get_wire_length(const struct libtrace_packet_t *packet);
[2c060e3]545
[7c8eacf]546/** Get the length of the capture framing headers.
547 * @param packet        the packet opaque pointer
548 * @returns the size of the packet as it was on the wire.
549 * @author Perry Lorier
550 * @author Daniel Lawson
551 * @note this length corresponds to the difference between the size of a
552 * captured packet in memory, and the captured length of the packet
553 */ 
554SIMPLE_FUNCTION
555int trace_get_framing_length(const struct libtrace_packet_t *packet);
556
557
[2c060e3]558/** Link layer types
[5395ce6]559 * This enumates the various different link types that libtrace understands
[2c060e3]560 */
561typedef enum { 
[5395ce6]562       TRACE_TYPE_LEGACY,       
[2c060e3]563       TRACE_TYPE_HDLC_POS, 
[5395ce6]564       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
[2c060e3]565       TRACE_TYPE_ATM,
[5395ce6]566       TRACE_TYPE_80211,                /**< 802.11 frames */
[c4be35b]567       TRACE_TYPE_NONE,
[5395ce6]568       TRACE_TYPE_LINUX_SLL,            /**< Linux "null" framing */
569       TRACE_TYPE_PFLOG,                /**< FreeBSD's PFlug */
[eaa5529]570       TRACE_TYPE_LEGACY_DEFAULT,
571       TRACE_TYPE_LEGACY_POS,
572       TRACE_TYPE_LEGACY_ATM,
573       TRACE_TYPE_LEGACY_ETH
[2c060e3]574     } libtrace_linktype_t;
575
576/** Get the type of the link layer
[2137b49]577 * @param packet        the packet opaque pointer
[2c060e3]578 * @returns libtrace_linktype_t
579 * @author Perry Lorier
580 * @author Daniel Lawson
581 */
[31709e8d]582SIMPLE_FUNCTION
[68667ee]583inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
[2c060e3]584
585/** Get the destination MAC addres
[2137b49]586 * @param packet        the packet opaque pointer
[2c060e3]587 * @returns a pointer to the destination mac, (or NULL if there is no
588 * destination MAC)
589 * @author Perry Lorier
590 */
[31709e8d]591SIMPLE_FUNCTION
[68667ee]592uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
[2c060e3]593
594/** Get the source MAC addres
[2137b49]595 * @param packet        the packet opaque pointer
[2c060e3]596 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
597 * @author Perry Lorier
598 */
[31709e8d]599SIMPLE_FUNCTION
[00c1935]600uint8_t *trace_get_source_mac(const struct libtrace_packet_t *packet);
[2c060e3]601
[80a2e99]602/** Truncate the packet at the suggested length
603 * @param packet        the packet opaque pointer
[31709e8d]604 * @param size          the new length of the packet
[80a2e99]605 * @returns the new length of the packet, or the original length of the
606 * packet if unchanged
607 * @author Daniel Lawson
608 */
[74c7660]609size_t trace_set_capture_length(struct libtrace_packet_t *packet, size_t size);
[80a2e99]610
611/** Set the direction flag, if it has one
612 * @param packet        the packet opaque pointer
613 * @param direction     the new direction (0,1,2,3)
614 * @returns a signed value containing the direction flag, or -1 if this is not supported
615 * @author Daniel Lawson
616 */
617int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
618
[14a9d05]619/** Get the direction flag, if it has one
[2137b49]620 * @param packet        the packet opaque pointer
[14a9d05]621 * @returns a signed value containing the direction flag, or -1 if this is not supported
[9075d49]622 * The direction is defined as 0 for packets originating locally (ie, outbound)
623 * and 1 for packets originating remotely (ie, inbound).
624 * Other values are possible, which might be overloaded to mean special things
625 * for a special trace.
[14a9d05]626 * @author Daniel Lawson
627 */
[31709e8d]628SIMPLE_FUNCTION
[68667ee]629int8_t trace_get_direction(const struct libtrace_packet_t *packet);
[14a9d05]630
[5395ce6]631/** Event types
[31709e8d]632 * see \ref libtrace_eventobj_t and \ref trace_event
[5395ce6]633 */
[2c060e3]634typedef enum {
[5395ce6]635        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
636        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
637        TRACE_EVENT_PACKET,     /**< packet has arrived */
638        TRACE_EVENT_TERMINATE   /**< End of trace */
[6cd7c20]639} libtrace_event_t;
[ef36351d]640
[68667ee]641/** structure returned by libtrace_event explaining what the current event is */
[6cd7c20]642struct libtrace_eventobj_t {
[5395ce6]643        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
[68667ee]644        int fd;                /**< if IOWAIT, the fd to sleep on */
645        double seconds;        /**< if SLEEP, the amount of time to sleep for */
[3cfa94a]646        int size;              /**< if PACKET, the value returned from trace_read_packet */
[063c879]647};
[2c060e3]648
649/** process a libtrace event
[ef36351d]650 * @param trace the libtrace opaque pointer
651 * @param packet the libtrace_packet opaque pointer
652 * @returns libtrace_event struct containing the type, and potential
653 *      fd or seconds to sleep on
654 *
655 * Type can be:
[31709e8d]656 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
657 *  TRACE_EVENT_SLEEP   Next event in seconds
658 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
[7bb7dda]659 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
[2c060e3]660 */
[6cd7c20]661struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
[ef36351d]662                struct libtrace_packet_t *packet);
[2c060e3]663
[c681e86]664/** setup a BPF filter
665 * @param filterstring a char * containing the bpf filter string
[c5a22ec]666 * @returns opaque pointer pointer to a libtrace_filter_t object
[c681e86]667 * @author Daniel Lawson
[fba4ca0]668 * @note The filter is not actually compiled at this point, so no correctness
669 * tests are performed here. trace_bpf_setfilter will always return ok, but
670 * if the filter is poorly constructed an error will be generated when the
671 * filter is actually used
[c681e86]672 */
[31709e8d]673SIMPLE_FUNCTION
[2137b49]674struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
[c681e86]675
676/** apply a BPF filter
[2137b49]677 * @param filter        the filter opaque pointer
678 * @param packet        the packet opaque pointer
[488432b]679 * @returns 0 if the filter fails, 1 if it succeeds
[c681e86]680 * @author Daniel Lawson
[fba4ca0]681 * @note Due to the way BPF filters are built, the filter is not actually compiled
682 * 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.
[c681e86]683 */
[2137b49]684int trace_bpf_filter(struct libtrace_filter_t *filter,
[58e9e02]685                const struct libtrace_packet_t *packet);
[c681e86]686
[83e0a25]687
[31709e8d]688/** Which port is the server port */
689typedef enum {
690        USE_DEST,       /**< Destination port is the server port */
691        USE_SOURCE      /**< Source port is the server port */
692} serverport_t;
[83e0a25]693
[58e9e02]694/** Get the source port
695 * @param packet        the packet to read from
696 * @returns a port in \em HOST byte order, or equivilent to ports for this
697 * protocol, or 0 if this protocol has no ports.
698 * @author Perry Lorier
699 */
[31709e8d]700SIMPLE_FUNCTION
[7e9d51c]701uint16_t trace_get_source_port(const struct libtrace_packet_t *packet);
[58e9e02]702
703/** Get the destination port
704 * @param packet        the packet to read from
705 * @returns a port in \em HOST byte order, or equivilent to ports for this
706 * protocol, or 0 if this protocol has no ports.
707 * @author Perry Lorier
708 */
[31709e8d]709SIMPLE_FUNCTION
[7e9d51c]710uint16_t trace_get_destination_port(const struct libtrace_packet_t *packet);
[58e9e02]711
[83e0a25]712/** hint at the server port in specified protocol
713 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
714 * @param source        the source port from the packet
715 * @param dest          the destination port from the packet
716 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
[fba4ca0]717 * @note ports must be in \em HOST byte order!
[83e0a25]718 * @author Daniel Lawson
719 */
[31709e8d]720SIMPLE_FUNCTION
[83e0a25]721int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
722
[de8c420b]723/** Takes a uri and splits it into a format and uridata component.
724 * Primarily for internal use but made available for external use.
725 * @param uri           the uri to be parsed
726 * @param format        destination location for the format component of the uri
727 * @returns 0 if an error occured, otherwise returns the uridata component
728 * @author Shane Alcock
729 */
[6f75b9d]730const char *trace_parse_uri(const char *uri, char **format);
[27615e9]731#ifdef __cplusplus
732} // extern "C"
[2137b49]733#endif // #ifdef __cplusplus
734#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.