source: lib/libtrace.h @ 62e170b

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

changes to new api

  • Property mode set to 100644
File size: 11.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 */
79struct libtrace_filter_t;
80
81/** Opaque structure holding information about a packet */
82#define LIBTRACE_PACKET_BUFSIZE 65536
83struct libtrace_packet_t {
84        struct libtrace_t *trace;
85        char buffer[LIBTRACE_PACKET_BUFSIZE];
86        size_t size;
87        uint8_t status;
88};
89
90/** Structure for dealing with IP packets */
91struct libtrace_ip
92  {
93#if __BYTE_ORDER == __LITTLE_ENDIAN
94    unsigned int ip_hl:4;               /**< header length */
95    unsigned int ip_v:4;                /**< version */
96#endif
97#if __BYTE_ORDER == __BIG_ENDIAN
98    unsigned int ip_v:4;                /**< version */
99    unsigned int ip_hl:4;               /**< header length */
100#endif
101    u_int8_t ip_tos;                    /**< type of service */
102    u_short ip_len;                     /**< total length */
103    u_short ip_id;                      /**< identification */
104    u_short ip_off;                     /**< fragment offset field */
105#define IP_RF 0x8000                    /**< reserved fragment flag */
106#define IP_DF 0x4000                    /**< dont fragment flag */
107#define IP_MF 0x2000                    /**< more fragments flag */
108#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
109    u_int8_t ip_ttl;                    /**< time to live */
110    u_int8_t ip_p;                      /**< protocol */
111    u_short ip_sum;                     /**< checksum */
112    struct in_addr ip_src, ip_dst;      /**< source and dest address */
113  };
114
115/** Structure for dealing with TCP packets */
116struct libtrace_tcp
117  {
118    u_int16_t source;           /**< Source Port */
119    u_int16_t dest;             /**< Destination port */
120    u_int32_t seq;              /**< Sequence number */
121    u_int32_t ack_seq;          /**< Acknowledgement Number */
122#  if __BYTE_ORDER == __LITTLE_ENDIAN
123    u_int16_t res1:4;           /**< Reserved bits */
124    u_int16_t doff:4;           
125    u_int16_t fin:1;            /**< FIN */
126    u_int16_t syn:1;            /**< SYN flag */
127    u_int16_t rst:1;            /**< RST flag */
128    u_int16_t psh:1;            /**< PuSH flag */
129    u_int16_t ack:1;            /**< ACK flag */
130    u_int16_t urg:1;            /**< URG flag */
131    u_int16_t res2:2;           /**< Reserved */
132#  elif __BYTE_ORDER == __BIG_ENDIAN
133    u_int16_t doff:4;           
134    u_int16_t res1:4;
135    u_int16_t res2:2;
136    u_int16_t urg:1;
137    u_int16_t ack:1;
138    u_int16_t psh:1;
139    u_int16_t rst:1;
140    u_int16_t syn:1;
141    u_int16_t fin:1;
142#  else
143#   error "Adjust your <bits/endian.h> defines"
144#  endif
145    u_int16_t window;           /**< Window Size */
146    u_int16_t check;            /**< Checksum */
147    u_int16_t urg_ptr;          /**< Urgent Pointer */
148};
149
150/** UDP Header for dealing with UDP packets */
151struct libtrace_udp {
152  u_int16_t     source;         /**< Source port */
153  u_int16_t     dest;           /**< Destination port */
154  u_int16_t     len;            /**< Length */
155  u_int16_t     check;          /**< Checksum */
156};
157
158/** ICMP Header for dealing with icmp packets */
159struct libtrace_icmp
160{
161  u_int8_t type;                /* message type */
162  u_int8_t code;                /* type sub-code */
163  u_int16_t checksum;
164  union
165  {
166    struct
167    {
168      u_int16_t id;
169      u_int16_t sequence;
170    } echo;                     /* echo datagram */
171    u_int32_t   gateway;        /* gateway address */
172    struct
173    {
174      u_int16_t __unused;
175      u_int16_t mtu;
176    } frag;                     /* path mtu discovery */
177  } un;
178};
179
180
181
182
183/** Create a trace file from a URI
184 *
185 * @returns opaque pointer to a libtrace_t
186 *
187 * Valid URI's are:
188 *  - erf:/path/to/erf/file
189 *  - erf:/path/to/erf/file.gz
190 *  - erf:/path/to/rtclient/socket
191 *  - erf:-  (stdin)
192 *  - dag:/dev/dagcard                  (implementd?)
193 *  - pcap:pcapinterface                (eg: pcap:eth0)
194 *  - pcap:/path/to/pcap/file
195 *  - pcap:/path/to/pcap/file.gz
196 *  - pcap:/path/to/pcap/socket         (implemented?)
197 *  - pcap:-
198 *  - rtclient:hostname
199 *  - rtclient:hostname:port
200 *  - wag:/path/to/wag/file
201 *  - wag:/path/to/wag/file.gz
202 *  - wag:/path/to/wag/socket
203 *  - wag:/dev/device
204 *
205 *  If an error occured why attempting to open the trace file, NULL is returned
206 *  and an error is output to stdout.
207 */
208struct libtrace_t *trace_create(char *uri);
209
210/** Close a trace file, freeing up any resources it may have been using
211 *
212 */
213void trace_destroy(struct libtrace_t *trace);
214
215/** Read one packet from the trace into buffer
216 *
217 * @param libtrace      the libtrace opaque pointer
218 * @param packet        the packet opaque pointer
219 * @returns false if it failed to read a packet
220 *
221 */
222int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
223
224/** get a pointer to the link layer
225 * @param packet        the packet opaque pointer
226 *
227 * @returns a pointer to the link layer, or NULL if there is no link layer
228 *
229 * @note you should call getLinkType() to find out what type of link layer
230 * this is
231 */
232void *trace_get_link(struct libtrace_packet_t *packet);
233
234/** get a pointer to the IP header (if any)
235 * @param packet        the packet opaque pointer
236 *
237 * @returns a pointer to the IP header, or NULL if there is not an IP packet
238 */
239struct libtrace_ip *trace_get_ip(struct libtrace_packet_t *packet);
240
241/** get a pointer to the TCP header (if any)
242 * @param packet        the packet opaque pointer
243 *
244 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
245 */
246struct libtrace_tcp *trace_get_tcp(struct libtrace_packet_t *packet);
247
248/** get a pointer to the UDP header (if any)
249 * @param packet        the packet opaque pointer
250 *
251 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
252 */
253struct libtrace_udp *trace_get_udp(struct libtrace_packet_t *packet);
254
255/** get a pointer to the ICMP header (if any)
256 * @param packet        the packet opaque pointer
257 *
258 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
259 */
260struct libtrace_icmp *trace_get_icmp(struct libtrace_packet_t *packet);
261
262/** Get the current time in DAG time format
263 * @param packet        the packet opaque pointer
264 *
265 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
266 * past 1970-01-01, the lower 32bits are partial seconds)
267 * @author Daniel Lawson
268 */
269uint64_t trace_get_erf_timestamp(struct libtrace_packet_t *packet);
270
271/** Get the current time in struct timeval
272 * @param packet        the packet opaque pointer
273 *
274 * @returns time that this packet was seen in a struct timeval
275 * @author Daniel Lawson
276 * @author Perry Lorier
277 */ 
278struct timeval trace_get_timeval(struct libtrace_packet_t *packet);
279
280/** Get the current time in floating point seconds
281 * @param packet        the packet opaque pointer
282 *
283 * @returns time that this packet was seen in 64bit floating point seconds
284 * @author Perry Lorier
285 */
286double trace_get_seconds(struct libtrace_packet_t *packet);
287
288/** Get the size of the packet in the trace
289 * @param packet        the packet opaque pointer
290 * @returns the size of the packet in the trace
291 * @author Perry Lorier
292 * @note Due to this being a header capture, or anonymisation, this may not
293 * be the same size as the original packet.  See get_wire_length() for the original
294 * size of the packet.
295 * @note This can (and often is) different for different packets in a trace!
296 * @par
297 *  This is sometimes called the "snaplen".
298 */
299
300int trace_get_capture_length(struct libtrace_packet_t *packet);
301
302/** Get the size of the packet as it was seen on the wire.
303 * @param packet        the packet opaque pointer
304 * @returns the size of the packet as it was on the wire.
305 * @author Perry Lorier
306 * @author Daniel Lawson
307 * @note Due to the trace being a header capture, or anonymisation this may
308 * not be the same as the Capture Len.
309 */ 
310
311int trace_get_wire_length(struct libtrace_packet_t *packet);
312
313/** Link layer types
314 */
315typedef enum { 
316       TRACE_TYPE_LEGACY, 
317       TRACE_TYPE_HDLC_POS, 
318       TRACE_TYPE_ETH,
319       TRACE_TYPE_ATM,
320       TRACE_TYPE_80211,
321     } libtrace_linktype_t;
322
323/** Get the type of the link layer
324 * @param packet        the packet opaque pointer
325 * @returns libtrace_linktype_t
326 * @author Perry Lorier
327 * @author Daniel Lawson
328 */
329
330inline libtrace_linktype_t trace_get_link_type(struct libtrace_packet_t *packet);
331
332/** Get the destination MAC addres
333 * @param packet        the packet opaque pointer
334 * @returns a pointer to the destination mac, (or NULL if there is no
335 * destination MAC)
336 * @author Perry Lorier
337 */
338uint8_t *trace_get_destination_mac(struct libtrace_packet_t *packet);
339
340/** Get the source MAC addres
341 * @param packet        the packet opaque pointer
342 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
343 * @author Perry Lorier
344 */
345uint8_t *trace_get_source_mac(struct libtrace_packet_t *packet);
346
347/** Get the direction flag, if it has one
348 * @param packet        the packet opaque pointer
349 * @returns a signed value containing the direction flag, or -1 if this is not supported
350 * @author Daniel Lawson
351 */
352int8_t trace_get_direction(struct libtrace_packet_t *packet);
353
354/** Event types */
355typedef enum {
356        TRACE_EVENT_IOWAIT,
357        TRACE_EVENT_SLEEP,
358        TRACE_EVENT_PACKET
359} libtrace_event_t;
360
361/** process a libtrace event
362 * @returns
363 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
364 *  TRACE_EVENT_SLEEP   Next event in <seconds>
365 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
366 */
367libtrace_event_t trace_event(struct libtrace_packet_t *packet,
368                int *fd,double *seconds);
369
370/** setup a BPF filter
371 * @param filterstring a char * containing the bpf filter string
372 * @returns opaque pointer pointer to a libtrace_filter_t object
373 * @author Daniel Lawson
374 */
375struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
376
377/** apply a BPF filter
378 * @param filter        the filter opaque pointer
379 * @param packet        the packet opaque pointer
380 * @returns the return value from bpf_filter
381 * @author Daniel Lawson
382 */
383int trace_bpf_filter(struct libtrace_filter_t *filter,
384                struct libtrace_packet_t *packet);
385
386#ifdef __cplusplus
387} // extern "C"
388#endif // #ifdef __cplusplus
389#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.