source: lib/libtrace.h @ 7e9d51c

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

tidying up examples to make sure they should compile

  • Property mode set to 100644
File size: 17.1 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#include <sys/types.h>
35#include <netinet/in.h>
36
37/** API version as 3 byte hex digits */
38#define LIBTRACE_API_VERSION 0x010010
39
40#ifdef __cplusplus
41extern "C" { 
42#endif
43/** @file
44 *
45 * @brief Trace file processing library header
46 *
47 * @author Daniel Lawson
48 * @author Perry Lorier
49 *
50 * @version $Id$
51 *
52 * This library provides a per packet interface into a trace file, or a live
53 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
54 * pcap etc.
55 *
56 * @par Usage
57 * <ol>
58 * <li> include "libtrace.h"
59 * <li> call create_trace with the uri of the trace you're interested in.<br>
60 * This is usually passed in as argv[1] to your program.
61 * <li> call libtrace_read_packet(), passing in the libtrace_t returned from
62 * create trace and a buffer (and the buffer length)
63 * <li> call getIP() on the buffer, and do whatever you need
64 * <li> loop back to step 3, until libtrace_read_packet() returns -1
65 * </ol>
66 * @par Linking
67 * To use this library you need to link against libtrace by passing -ltrace
68 * to your linker. You may also need to link against a version of libpcap
69 * and of zlib which are compiled for largefile support (if you wish to access
70 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
71 * Woody, at least, does not support large file offsets.
72 *
73 */
74
75#define COLLECTOR_PORT 3435
76
77/** Opaque structure holding information about a trace */
78struct libtrace_t;
79       
80/** Opaque structure holding information about a bpf filter */
81struct libtrace_filter_t;
82
83/** Opaque structure holding information about a packet */
84#define LIBTRACE_PACKET_BUFSIZE 65536
85struct libtrace_packet_t {
86        struct libtrace_t *trace;
87        //void *buffer;
88        char buffer[LIBTRACE_PACKET_BUFSIZE];
89        size_t size;
90        uint8_t status;
91};
92
93/** Structure for dealing with IP packets */
94struct libtrace_ip
95  {
96#if BYTE_ORDER == LITTLE_ENDIAN
97    unsigned int ip_hl:4;               /**< header length */
98    unsigned int ip_v:4;                /**< version */
99#elif BYTE_ORDER == BIG_ENDIAN
100    unsigned int ip_v:4;                /**< version */
101    unsigned int ip_hl:4;               /**< header length */
102#else
103#   error "Adjust your <bits/endian.h> defines"
104#endif
105    u_int8_t ip_tos;                    /**< type of service */
106    u_short ip_len;                     /**< total length */
107    u_short ip_id;                      /**< identification */
108    u_short ip_off;                     /**< fragment offset field */
109#define IP_RF 0x8000                    /**< reserved fragment flag */
110#define IP_DF 0x4000                    /**< dont fragment flag */
111#define IP_MF 0x2000                    /**< more fragments flag */
112#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
113    u_int8_t ip_ttl;                    /**< time to live */
114    u_int8_t ip_p;                      /**< protocol */
115    u_short ip_sum;                     /**< checksum */
116    struct in_addr ip_src;              /**< source address */
117    struct in_addr ip_dst;              /**< dest address */
118  };
119
120/** Structure for dealing with TCP packets */
121struct libtrace_tcp
122  {
123    u_int16_t source;           /**< Source Port */
124    u_int16_t dest;             /**< Destination port */
125    u_int32_t seq;              /**< Sequence number */
126    u_int32_t ack_seq;          /**< Acknowledgement Number */
127#  if BYTE_ORDER == LITTLE_ENDIAN
128    u_int16_t res1:4;           /**< Reserved bits */
129    u_int16_t doff:4;           
130    u_int16_t fin:1;            /**< FIN */
131    u_int16_t syn:1;            /**< SYN flag */
132    u_int16_t rst:1;            /**< RST flag */
133    u_int16_t psh:1;            /**< PuSH flag */
134    u_int16_t ack:1;            /**< ACK flag */
135    u_int16_t urg:1;            /**< URG flag */
136    u_int16_t res2:2;           /**< Reserved */
137#  elif BYTE_ORDER == BIG_ENDIAN
138    u_int16_t doff:4;           
139    u_int16_t res1:4;           /**< Reserved bits */
140    u_int16_t res2:2;           /**< Reserved */
141    u_int16_t urg:1;            /**< URG flag */
142    u_int16_t ack:1;            /**< ACK flag */
143    u_int16_t psh:1;            /**< PuSH flag */
144    u_int16_t rst:1;            /**< RST flag */
145    u_int16_t syn:1;            /**< SYN flag */
146    u_int16_t fin:1;            /**< FIN flag */
147#  else
148#   error "Adjust your <bits/endian.h> defines"
149#  endif
150    u_int16_t window;           /**< Window Size */
151    u_int16_t check;            /**< Checksum */
152    u_int16_t urg_ptr;          /**< Urgent Pointer */
153};
154
155/** UDP Header for dealing with UDP packets */
156struct libtrace_udp {
157  u_int16_t     source;         /**< Source port */
158  u_int16_t     dest;           /**< Destination port */
159  u_int16_t     len;            /**< Length */
160  u_int16_t     check;          /**< Checksum */
161};
162
163/** ICMP Header for dealing with icmp packets */
164struct libtrace_icmp
165{
166  u_int8_t type;                /**< message type */
167  u_int8_t code;                /**< type sub-code */
168  u_int16_t checksum;           /**< checksum */
169  union
170  {
171    struct
172    {
173      u_int16_t id;
174      u_int16_t sequence;
175    } echo;                     /**< echo datagram */
176    u_int32_t   gateway;        /**< gateway address */
177    struct
178    {
179      u_int16_t unused;
180      u_int16_t mtu;
181    } frag;                     /**< path mtu discovery */
182  } un;
183};
184
185
186
187
188/** Create a trace file from a URI
189 *
190 * @returns opaque pointer to a libtrace_t
191 *
192 * Valid URI's are:
193 *  - erf:/path/to/erf/file
194 *  - erf:/path/to/erf/file.gz
195 *  - erf:/path/to/rtclient/socket
196 *  - erf:-  (stdin)
197 *  - dag:/dev/dagcard                  (implementd?)
198 *  - pcap:pcapinterface                (eg: pcap:eth0)
199 *  - pcap:/path/to/pcap/file
200 *  - pcap:/path/to/pcap/file.gz
201 *  - pcap:/path/to/pcap/socket         (implemented?)
202 *  - pcap:-
203 *  - rtclient:hostname
204 *  - rtclient:hostname:port
205 *  - wag:/path/to/wag/file
206 *  - wag:/path/to/wag/file.gz
207 *  - wag:/path/to/wag/socket
208 *  - wag:/dev/device
209 *
210 *  If an error occured why attempting to open the trace file, NULL is returned
211 *  and an error is output to stdout.
212 */
213struct libtrace_t *trace_create(char *uri);
214
215/** Close a trace file, freeing up any resources it may have been using
216 *
217 */
218void trace_destroy(struct libtrace_t *trace);
219
220/** Read one packet from the trace into buffer
221 *
222 * @param libtrace      the libtrace opaque pointer
223 * @param packet        the packet opaque pointer
224 * @returns false if it failed to read a packet
225 *
226 */
227int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
228
229/** get a pointer to the link layer
230 * @param packet        the packet opaque pointer
231 *
232 * @returns a pointer to the link layer, or NULL if there is no link layer
233 *
234 * @note you should call getLinkType() to find out what type of link layer
235 * this is
236 */
237void *trace_get_link(const struct libtrace_packet_t *packet);
238
239/** get a pointer to the IP header (if any)
240 * @param packet        the packet opaque pointer
241 *
242 * @returns a pointer to the IP header, or NULL if there is not an IP packet
243 */
244struct libtrace_ip *trace_get_ip(const struct libtrace_packet_t *packet);
245
246/** get a pointer to the TCP header (if any)
247 * @param packet        the packet opaque pointer
248 *
249 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
250 */
251struct libtrace_tcp *trace_get_tcp(const struct libtrace_packet_t *packet);
252
253/** get a pointer to the TCP header (if any) given a pointer to the IP header
254 * @param ip            The IP header
255 * @param[out] skipped  An output variable of the number of bytes skipped
256 *
257 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
258 *
259 * Skipped can be NULL, in which case it will be ignored by the program.
260 *
261 * @author Perry Lorier
262 */
263struct libtrace_tcp *trace_get_tcp_from_ip(struct libtrace_ip *ip,int *skipped);
264
265/** get a pointer to the UDP header (if any)
266 * @param packet        the packet opaque pointer
267 *
268 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
269 */
270struct libtrace_udp *trace_get_udp(const struct libtrace_packet_t *packet);
271
272/** get a pointer to the UDP header (if any) given a pointer to the IP header
273 * @param       ip      The IP header
274 * @param[out]  skipped An output variable of the number of bytes skipped
275 *
276 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
277 *
278 * Skipped may be NULL, in which case it will be ignored by this function.
279 */
280struct libtrace_udp *trace_get_udp_from_ip(struct libtrace_ip *ip,int *skipped);
281
282/** get a pointer to the ICMP header (if any)
283 * @param packet        the packet opaque pointer
284 *
285 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
286 */
287struct libtrace_icmp *trace_get_icmp(const struct libtrace_packet_t *packet);
288
289/** get a pointer to the ICMP header (if any) given a pointer to the IP header
290 * @param ip            The IP header
291 * @param[out] skipped  An output variable of the number of bytes skipped
292 *
293 * @returns a pointer to the ICMP header, or NULL if this is not an ICMP packet
294 *
295 * Skipped may be NULL, in which case it will be ignored by this function
296 */
297struct libtrace_icmp *trace_get_icmp_from_ip(struct libtrace_ip *ip,int *skipped);
298
299/** parse an ip or tcp option
300 * @param[in,out] ptr   the pointer to the current option
301 * @param[in,out] len   the length of the remaining buffer
302 * @param[out] type     the type of the option
303 * @param[out] optlen   the length of the option
304 * @param[out] data     the data of the option
305 *
306 * @returns bool true if there is another option (and the fields are filled in)
307 *               or false if this was the last option.
308 *
309 * This updates ptr to point to the next option after this one, and updates
310 * len to be the number of bytes remaining in the options area.  Type is updated
311 * to be the code of this option, and data points to the data of this option,
312 * with optlen saying how many bytes there are.
313 *
314 * @note Beware of fragmented packets.
315 */
316int trace_get_next_option(unsigned char **ptr,int *len,
317                        unsigned char *type,
318                        unsigned char *optlen,
319                        unsigned char **data);
320
321
322/** Get the current time in DAG time format
323 * @param packet        the packet opaque pointer
324 *
325 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
326 * past 1970-01-01, the lower 32bits are partial seconds)
327 * @author Daniel Lawson
328 */
329uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
330
331/** Get the current time in struct timeval
332 * @param packet        the packet opaque pointer
333 *
334 * @returns time that this packet was seen in a struct timeval
335 * @author Daniel Lawson
336 * @author Perry Lorier
337 */ 
338struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
339
340/** Get the current time in floating point seconds
341 * @param packet        the packet opaque pointer
342 *
343 * @returns time that this packet was seen in 64bit floating point seconds
344 * @author Perry Lorier
345 */
346double trace_get_seconds(const struct libtrace_packet_t *packet);
347
348/** Get the size of the packet in the trace
349 * @param packet        the packet opaque pointer
350 * @returns the size of the packet in the trace
351 * @author Perry Lorier
352 * @note Due to this being a header capture, or anonymisation, this may not
353 * be the same size as the original packet.  See get_wire_length() for the original
354 * size of the packet.
355 * @note This can (and often is) different for different packets in a trace!
356 * @par
357 *  This is sometimes called the "snaplen".
358 */
359
360int trace_get_capture_length(const struct libtrace_packet_t *packet);
361
362/** Get the size of the packet as it was seen on the wire.
363 * @param packet        the packet opaque pointer
364 * @returns the size of the packet as it was on the wire.
365 * @author Perry Lorier
366 * @author Daniel Lawson
367 * @note Due to the trace being a header capture, or anonymisation this may
368 * not be the same as the Capture Len.
369 */ 
370
371int trace_get_wire_length(const struct libtrace_packet_t *packet);
372
373/** Link layer types
374 */
375typedef enum { 
376       TRACE_TYPE_LEGACY, 
377       TRACE_TYPE_HDLC_POS, 
378       TRACE_TYPE_ETH,
379       TRACE_TYPE_ATM,
380       TRACE_TYPE_80211,
381       TRACE_TYPE_NONE,
382       TRACE_TYPE_LINUX_SLL,
383       TRACE_TYPE_PFLOG
384     } libtrace_linktype_t;
385
386/** Get the type of the link layer
387 * @param packet        the packet opaque pointer
388 * @returns libtrace_linktype_t
389 * @author Perry Lorier
390 * @author Daniel Lawson
391 */
392
393inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
394
395/** Get the destination MAC addres
396 * @param packet        the packet opaque pointer
397 * @returns a pointer to the destination mac, (or NULL if there is no
398 * destination MAC)
399 * @author Perry Lorier
400 */
401uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
402
403/** Get the source MAC addres
404 * @param packet        the packet opaque pointer
405 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
406 * @author Perry Lorier
407 */
408uint8_t *trace_get_source_mac(const struct libtrace_packet_t *packet);
409
410/** Truncate the packet at the suggested length
411 * @param packet        the packet opaque pointer
412 * @param len           the new length of the packet
413 * @returns the new length of the packet, or the original length of the
414 * packet if unchanged
415 * @author Daniel Lawson
416 */
417size_t trace_truncate_packet(struct libtrace_packet_t *packet, size_t size);
418
419/** Set the direction flag, if it has one
420 * @param packet        the packet opaque pointer
421 * @param direction     the new direction (0,1,2,3)
422 * @returns a signed value containing the direction flag, or -1 if this is not supported
423 * @author Daniel Lawson
424 */
425int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
426
427/** Get the direction flag, if it has one
428 * @param packet        the packet opaque pointer
429 * @returns a signed value containing the direction flag, or -1 if this is not supported
430 * The direction is defined as 0 for packets originating locally (ie, outbound)
431 * and 1 for packets originating remotely (ie, inbound).
432 * Other values are possible, which might be overloaded to mean special things
433 * for a special trace.
434 * @author Daniel Lawson
435 */
436int8_t trace_get_direction(const struct libtrace_packet_t *packet);
437
438/** Event types */
439typedef enum {
440        TRACE_EVENT_IOWAIT,
441        TRACE_EVENT_SLEEP,
442        TRACE_EVENT_PACKET,
443        TRACE_EVENT_TERMINATE
444} libtrace_event_t;
445
446/** structure returned by libtrace_event explaining what the current event is */
447struct libtrace_eventobj_t {
448        libtrace_event_t type; /**< event type (iowait,sleep,packet */
449        int fd;                /**< if IOWAIT, the fd to sleep on */
450        double seconds;        /**< if SLEEP, the amount of time to sleep for */
451        int size;              /**< if PACKET, the value returned from trace_read_packet */
452};
453
454/** process a libtrace event
455 * @param trace the libtrace opaque pointer
456 * @param packet the libtrace_packet opaque pointer
457 * @param fd a pointer to a file descriptor to listen on
458 * @param seconds a pointer the time in seconds since to the next event
459 * @returns libtrace_event struct containing the type, and potential
460 *      fd or seconds to sleep on
461 *
462 * Type can be:
463 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
464 *  TRACE_EVENT_SLEEP   Next event in <seconds>
465 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
466 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
467 */
468struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
469                struct libtrace_packet_t *packet);
470
471/** setup a BPF filter
472 * @param filterstring a char * containing the bpf filter string
473 * @returns opaque pointer pointer to a libtrace_filter_t object
474 * @author Daniel Lawson
475 */
476struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
477
478/** apply a BPF filter
479 * @param filter        the filter opaque pointer
480 * @param packet        the packet opaque pointer
481 * @returns 0 if the filter fails, 1 if it succeeds
482 * @author Daniel Lawson
483 */
484int trace_bpf_filter(struct libtrace_filter_t *filter,
485                const struct libtrace_packet_t *packet);
486
487
488typedef enum {USE_DEST, USE_SOURCE} serverport_t;
489
490/** Get the source port
491 * @param packet        the packet to read from
492 * @returns a port in \em HOST byte order, or equivilent to ports for this
493 * protocol, or 0 if this protocol has no ports.
494 * @author Perry Lorier
495 */
496uint16_t trace_get_source_port(const struct libtrace_packet_t *packet);
497
498/** Get the destination port
499 * @param packet        the packet to read from
500 * @returns a port in \em HOST byte order, or equivilent to ports for this
501 * protocol, or 0 if this protocol has no ports.
502 * @author Perry Lorier
503 */
504uint16_t trace_get_destination_port(const struct libtrace_packet_t *packet);
505
506/** hint at the server port in specified protocol
507 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
508 * @param source        the source port from the packet
509 * @param dest          the destination port from the packet
510 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
511 * @note ports must be in \em host byte order!
512 * @author Daniel Lawson
513 */
514int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
515
516#ifdef __cplusplus
517} // extern "C"
518#endif // #ifdef __cplusplus
519#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.