source: lib/libtrace.h @ 750a1e0

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

.

  • Property mode set to 100644
File size: 13.7 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 <features.h>
35#include <sys/types.h>
36#include <netinet/in.h>
37
38#ifdef __cplusplus
39extern "C" { 
40#endif
41/** @file
42 *
43 * @brief Trace file processing library header
44 *
45 * @author Daniel Lawson
46 * @author Perry Lorier
47 *
48 * @version $Id$
49 *
50 * This library provides a per packet interface into a trace file, or a live
51 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
52 * pcap etc.
53 *
54 * @par Usage
55 * <ol>
56 * <li> include "libtrace.h"
57 * <li> call create_trace with the uri of the trace you're interested in.<br>
58 * This is usually passed in as argv[1] to your program.
59 * <li> call libtrace_read_packet(), passing in the libtrace_t returned from
60 * create trace and a buffer (and the buffer length)
61 * <li> call getIP() on the buffer, and do whatever you need
62 * <li> loop back to step 3, until libtrace_read_packet() returns -1
63 * </ol>
64 * @par Linking
65 * To use this library you need to link against libtrace by passing -ltrace
66 * to your linker. You may also need to link against a version of libpcap
67 * and of zlib which are compiled for largefile support (if you wish to access
68 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
69 * Woody, at least, does not support large files offsets.
70 *
71 */
72
73#define COLLECTOR_PORT 3435
74
75/** Opaque structure holding information about a trace */
76struct libtrace_t;
77       
78/** Opaque structure holding information about a bpf filter */
79
80struct libtrace_filter_t;
81/** Structure for dealing with IP packets */
82struct libtrace_ip
83  {
84#if __BYTE_ORDER == __LITTLE_ENDIAN
85    unsigned int ip_hl:4;               /**< header length */
86    unsigned int ip_v:4;                /**< version */
87#endif
88#if __BYTE_ORDER == __BIG_ENDIAN
89    unsigned int ip_v:4;                /**< version */
90    unsigned int ip_hl:4;               /**< header length */
91#endif
92    u_int8_t ip_tos;                    /**< type of service */
93    u_short ip_len;                     /**< total length */
94    u_short ip_id;                      /**< identification */
95    u_short ip_off;                     /**< fragment offset field */
96#define IP_RF 0x8000                    /**< reserved fragment flag */
97#define IP_DF 0x4000                    /**< dont fragment flag */
98#define IP_MF 0x2000                    /**< more fragments flag */
99#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
100    u_int8_t ip_ttl;                    /**< time to live */
101    u_int8_t ip_p;                      /**< protocol */
102    u_short ip_sum;                     /**< checksum */
103    struct in_addr ip_src, ip_dst;      /**< source and dest address */
104  };
105
106/** Structure for dealing with TCP packets */
107struct libtrace_tcp
108  {
109    u_int16_t source;           /**< Source Port */
110    u_int16_t dest;             /**< Destination port */
111    u_int32_t seq;              /**< Sequence number */
112    u_int32_t ack_seq;          /**< Acknowledgement Number */
113#  if __BYTE_ORDER == __LITTLE_ENDIAN
114    u_int16_t res1:4;           /**< Reserved bits */
115    u_int16_t doff:4;           
116    u_int16_t fin:1;            /**< FIN */
117    u_int16_t syn:1;            /**< SYN flag */
118    u_int16_t rst:1;            /**< RST flag */
119    u_int16_t psh:1;            /**< PuSH flag */
120    u_int16_t ack:1;            /**< ACK flag */
121    u_int16_t urg:1;            /**< URG flag */
122    u_int16_t res2:2;           /**< Reserved */
123#  elif __BYTE_ORDER == __BIG_ENDIAN
124    u_int16_t doff:4;           
125    u_int16_t res1:4;
126    u_int16_t res2:2;
127    u_int16_t urg:1;
128    u_int16_t ack:1;
129    u_int16_t psh:1;
130    u_int16_t rst:1;
131    u_int16_t syn:1;
132    u_int16_t fin:1;
133#  else
134#   error "Adjust your <bits/endian.h> defines"
135#  endif
136    u_int16_t window;           /**< Window Size */
137    u_int16_t check;            /**< Checksum */
138    u_int16_t urg_ptr;          /**< Urgent Pointer */
139};
140
141/** UDP Header for dealing with UDP packets */
142struct libtrace_udp {
143  u_int16_t     source;         /**< Source port */
144  u_int16_t     dest;           /**< Destination port */
145  u_int16_t     len;            /**< Length */
146  u_int16_t     check;          /**< Checksum */
147};
148
149/** ICMP Header for dealing with icmp packets */
150struct libtrace_icmp
151{
152  u_int8_t type;                /* message type */
153  u_int8_t code;                /* type sub-code */
154  u_int16_t checksum;
155  union
156  {
157    struct
158    {
159      u_int16_t id;
160      u_int16_t sequence;
161    } echo;                     /* echo datagram */
162    u_int32_t   gateway;        /* gateway address */
163    struct
164    {
165      u_int16_t __unused;
166      u_int16_t mtu;
167    } frag;                     /* path mtu discovery */
168  } un;
169};
170
171
172
173
174/** Create a trace file from a URI
175 *
176 * @returns opaque pointer to a libtrace_t
177 *
178 * Valid URI's are:
179 *  - erf:/path/to/erf/file
180 *  - erf:/path/to/erf/file.gz
181 *  - erf:/path/to/rtclient/socket
182 *  - erf:-  (stdin)
183 *  - dag:/dev/dagcard                  (implementd?)
184 *  - pcap:pcapinterface                (eg: pcap:eth0)
185 *  - pcap:/path/to/pcap/file
186 *  - pcap:/path/to/pcap/file.gz
187 *  - pcap:/path/to/pcap/socket         (implemented?)
188 *  - pcap:-
189 *  - rtclient:hostname
190 *  - rtclient:hostname:port
191 *  - wag:/path/to/wag/file
192 *  - wag:/path/to/wag/file.gz
193 *  - wag:/path/to/wag/socket
194 *  - wag:/dev/device
195 *
196 *  If an error occured why attempting to open the trace file, NULL is returned
197 *  and an error is output to stdout.
198 */
199struct libtrace_t *create_trace(char *uri);
200
201/** Close a trace file, freeing up any resources it may have been using
202 *
203 */
204void destroy_trace(struct libtrace_t *rtclient);
205
206/** Read one packet from the trace into buffer
207 *
208 * @param libtrace      the trace to read from
209 * @param buffer        the buffer to read into
210 * @param len           the length of the buffer
211 * @param status        status of the trace (only used for RTClients)
212 * @returns number of bytes copied, -1 on error, or 0 at EOF
213 *
214 * @note the buffer must be at least as large as the largest packet (plus
215 * link layer, and trace packet metadata overhead)
216 */
217int libtrace_read_packet(struct libtrace_t *rtclient, void *buffer, size_t len, int *status);
218
219/** get a pointer to the link layer
220 * @param libtrace      a pointer to the trace object returned from gettrace
221 * @param buffer        a pointer to a filled in buffer
222 * @param buflen        a pointer to the size of the buffer
223 *
224 * @returns a pointer to the link layer, or NULL if there is no link layer
225 *
226 * @note you should call getLinkType() to find out what type of link layer
227 * this is
228 */
229void *get_link(struct libtrace_t *libtrace, void *buffer, int buflen);
230
231/** get a pointer to the IP header (if any)
232 * @param libtrace      a pointer to the trace object returned from gettrace
233 * @param buffer        a pointer to a filled in buffer
234 * @param buflen        a pointer to the size of the buffer
235 *
236 * @returns a pointer to the IP header, or NULL if there is not an IP packet
237 */
238struct libtrace_ip *get_ip(struct libtrace_t *libtrace, void *buffer, int buflen);
239
240/** get a pointer to the TCP header (if any)
241 * @param libtrace      a pointer to the trace object returned from gettrace
242 * @param buffer        a pointer to a filled in buffer
243 * @param buflen        a pointer to the size of the buffer
244 *
245 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
246 */
247struct libtrace_tcp *get_tcp(struct libtrace_t *libtrace, void *buffer, int buflen);
248
249/** get a pointer to the UDP header (if any)
250 * @param libtrace      a pointer to the trace object returned from gettrace
251 * @param buffer        a pointer to a filled in buffer
252 * @param buflen        a pointer to the size of the buffer
253 *
254 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
255 */
256struct libtrace_udp *get_udp(struct libtrace_t *libtrace, void *buffer, int buflen);
257
258/** get a pointer to the ICMP header (if any)
259 * @param libtrace      a pointer to the trace object returned from gettrace
260 * @param buffer        a pointer to a filled in buffer
261 * @param buflen        a pointer to the size of the buffer
262 *
263 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
264 */
265struct libtrace_icmp *get_icmp(struct libtrace_t *libtrace, void *buffer, int buflen);
266
267/** Get the current time in DAG time format
268 * @param libtrace the libtrace opaque pointer
269 * @param buffer a pointer to a filled in buffer
270 * @param buflen the length of the buffer
271 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
272 * past 1970-01-01, the lower 32bits are partial seconds)
273 * @author Daniel Lawson
274 */
275uint64_t get_erf_timestamp(struct libtrace_t *libtrace, void *buffer, int buflen);
276
277/** Get the current time in struct timeval
278 * @param libtrace the libtrace opaque pointer
279 * @param buffer a pointer to a filled in buffer
280 * @param buflen the length of the buffer
281 * @returns time that this packet was seen in a struct timeval
282 * @author Daniel Lawson
283 * @author Perry Lorier
284 */ 
285
286struct timeval get_timeval(struct libtrace_t *libtrace, void *buffer, int buflen);
287
288/** Get the current time in floating point seconds
289 * @param libtrace the libtrace opaque pointer
290 * @param buffer a pointer to a filled in buffer
291 * @param buflen the length of the buffer
292 * @returns time that this packet was seen in 64bit floating point seconds
293 * @author Perry Lorier
294 */
295double get_seconds(struct libtrace_t *libtrace, void *buffer, int buflen);
296
297/** Get the size of the packet in the trace
298 * @param libtrace the libtrace opaque pointer
299 * @param buffer a pointer to a filled in buffer
300 * @param buflen the length of the buffer
301 * @returns the size of the packet in the trace
302 * @author Perry Lorier
303 * @note Due to this being a header capture, or anonymisation, this may not
304 * be the same size as the original packet.  See get_wire_length() for the original
305 * size of the packet.
306 * @note This can (and often is) different for different packets in a trace!
307 * @par
308 *  This is sometimes called the "snaplen".
309 */
310
311int get_capture_length(struct libtrace_t *libtrace, void *buffer, int buflen);
312
313/** Get the size of the packet as it was seen on the wire.
314 * @param libtrace the libtrace opaque pointer
315 * @param buffer a pointer to a filled in buffer
316 * @param buflen the length of the buffer
317 * @returns the size of the packet as it was on the wire.
318 * @author Perry Lorier
319 * @author Daniel Lawson
320 * @note Due to the trace being a header capture, or anonymisation this may
321 * not be the same as the Capture Len.
322 */ 
323
324int get_wire_length(struct libtrace_t *libtrace, void *buffer, int buflen);
325
326/** Link layer types
327 */
328typedef enum { 
329       TRACE_TYPE_LEGACY, 
330       TRACE_TYPE_HDLC_POS, 
331       TRACE_TYPE_ETH,
332       TRACE_TYPE_ATM,
333       TRACE_TYPE_80211,
334     } libtrace_linktype_t;
335
336/** Get the type of the link layer
337 * @param libtrace the libtrace opaque pointer
338 * @param buffer a pointer to a filled in buffer
339 * @param buflen the length of the buffer
340 * @returns libtrace_linktype_t
341 * @author Perry Lorier
342 * @author Daniel Lawson
343 */
344
345inline libtrace_linktype_t get_link_type(
346                struct libtrace_t *libtrace,
347                void *buffer,
348                int buflen);   
349
350/** Get the destination MAC addres
351 * @param libtrace the libtrace opaque pointer
352 * @param buffer a pointer to a filled in buffer
353 * @param buflen the length of the buffer
354 * @returns a pointer to the destination mac, (or NULL if there is no
355 * destination MAC)
356 * @author Perry Lorier
357 */
358uint8_t *get_destination_mac(struct libtrace_t *libtrace,
359                        void *buffer,
360                        int buflen);
361
362/** Get the source MAC addres
363 * @param libtrace the libtrace opaque pointer
364 * @param buffer a pointer to a filled in buffer
365 * @param buflen the length of the buffer
366 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
367 * @author Perry Lorier
368 */
369uint8_t *get_source_mac(struct libtrace_t *libtrace,
370                        void *buffer,
371                        int buflen);
372
373/** Get the direction flag, if it has one
374 * @param libtrace the libtrace opaque pointer
375 * @param buffer a point to a fille in buffer
376 * @param buflen the length of the buffer
377 * @returns a signed value containing the direction flag, or -1 if this is not supported
378 * @author Daniel Lawson
379 */
380int8_t get_direction(struct libtrace_t *libtrace,
381                      void *buffer,
382                      int buflen);
383
384/** Event types */
385typedef enum {
386        TRACE_EVENT_IOWAIT,
387        TRACE_EVENT_SLEEP,
388        TRACE_EVENT_PACKET
389} libtrace_event_t;
390
391/** process a libtrace event
392 * @returns
393 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
394 *  TRACE_EVENT_SLEEP   Next event in <seconds>
395 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
396 */
397libtrace_event_t libtrace_event(struct libtrace_t *trace,
398                        int *fd,double *seconds,
399                        void *buffer, size_t len, int *size);
400
401/** setup a BPF filter
402 * @param filterstring a char * containing the bpf filter string
403 * @returns opaque pointer pointer to a libtrace_filter_t object
404 * @author Daniel Lawson
405 */
406struct libtrace_filter_t *libtrace_bpf_setfilter(const char *filterstring);
407
408/** apply a BPF filter
409 * @param libtrace the libtrace opaque pointer
410 * @param filter the filter opaque pointer
411 * @param buffer a pointer to a filled buffer
412 * @param buflen the length of the buffer
413 * @returns the return value from bpf_filter
414 * @author Daniel Lawson
415 */
416int libtrace_bpf_filter(struct libtrace_t *trace,
417                        struct libtrace_filter_t *filter,
418                        void *buffer, 
419                        int buflen);
420
421#ifdef __cplusplus
422} // extern "C"
423#endif // #ifdef _cplusplus
424#endif // _LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.