source: lib/libtrace.h @ 9c4b5e3

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

Added support for nonblocking events for format_rt

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