A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
pcap-file.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Craig Dowell (craigdo@ee.washington.edu)
7 */
8
9#ifndef PCAP_FILE_H
10#define PCAP_FILE_H
11
12#include "ns3/ptr.h"
13
14#include <fstream>
15#include <stdint.h>
16#include <string>
17
18namespace ns3
19{
20
21class Packet;
22class Header;
23
24/**
25 * @brief A class representing a pcap file
26 *
27 * A class representing a pcap file. This allows easy creation, writing and
28 * reading of files composed of stored packets; which may be viewed using
29 * standard tools.
30 */
32{
33 public:
34 static const int32_t ZONE_DEFAULT = 0; //!< Time zone offset for current location
36 65535; //!< Default value for maximum octets to save per packet
37
38 public:
39 PcapFile();
40 ~PcapFile();
41
42 /**
43 * @return true if the 'fail' bit is set in the underlying iostream, false otherwise.
44 */
45 bool Fail() const;
46 /**
47 * @return true if the 'eof' bit is set in the underlying iostream, false otherwise.
48 */
49 bool Eof() const;
50 /**
51 * Clear all state bits of the underlying iostream.
52 */
53 void Clear();
54
55 /**
56 * Create a new pcap file or open an existing pcap file. Semantics are
57 * similar to the stdc++ io stream classes, but differ in that
58 * positions in the file are based on packets not characters. For example
59 * if the file is opened for reading, the file position indicator (seek
60 * position) points to the beginning of the first packet in the file, not
61 * zero (which would point to the start of the pcap header).
62 *
63 * Since a pcap file is always a binary file, the file type is automatically
64 * selected as a binary file (fstream::binary is automatically ored with the mode
65 * field).
66 *
67 * @param filename String containing the name of the file.
68 *
69 * @param mode the access mode for the file.
70 */
71 void Open(const std::string& filename, std::ios::openmode mode);
72
73 /**
74 * Close the underlying file.
75 */
76 void Close();
77
78 /**
79 * Initialize the pcap file associated with this object. This file must have
80 * been previously opened with write permissions.
81 *
82 * @param dataLinkType A data link type as defined in the pcap library. If
83 * you want to make resulting pcap files visible in existing tools, the
84 * data link type must match existing definitions, such as PCAP_ETHERNET,
85 * PCAP_PPP, PCAP_80211, etc. If you are storing different kinds of packet
86 * data, such as naked TCP headers, you are at liberty to locally define your
87 * own data link types. According to the pcap-linktype man page, "well-known"
88 * pcap linktypes range from 0 to 263. If you use a large random number for
89 * your type, chances are small for a collision.
90 *
91 * @param snapLen An optional maximum size for packets written to the file.
92 * Defaults to 65535. If packets exceed this length they are truncated.
93 *
94 * @param timeZoneCorrection An integer describing the offset of your local
95 * time zone from UTC/GMT. For example, Pacific Standard Time in the US is
96 * GMT-8, so one would enter -8 for that correction. Defaults to 0 (UTC).
97 *
98 * @param swapMode Flag indicating a difference in endianness of the
99 * writing system. Defaults to false.
100 *
101 * @param nanosecMode Flag indicating the time resolution of the writing
102 * system. Default to false.
103 *
104 * @warning Calling this method on an existing file will result in the loss
105 * any existing data.
106 */
107 void Init(uint32_t dataLinkType,
108 uint32_t snapLen = SNAPLEN_DEFAULT,
109 int32_t timeZoneCorrection = ZONE_DEFAULT,
110 bool swapMode = false,
111 bool nanosecMode = false);
112
113 /**
114 * @brief Write next packet to file
115 *
116 * @param tsSec Packet timestamp, seconds
117 * @param tsUsec Packet timestamp, microseconds
118 * @param data Data buffer
119 * @param totalLen Total packet length
120 *
121 */
122 void Write(uint32_t tsSec, uint32_t tsUsec, const uint8_t* const data, uint32_t totalLen);
123
124 /**
125 * @brief Write next packet to file
126 *
127 * @param tsSec Packet timestamp, seconds
128 * @param tsUsec Packet timestamp, microseconds
129 * @param p Packet to write
130 *
131 */
132 void Write(uint32_t tsSec, uint32_t tsUsec, Ptr<const Packet> p);
133 /**
134 * @brief Write next packet to file
135 *
136 * @param tsSec Packet timestamp, seconds
137 * @param tsUsec Packet timestamp, microseconds
138 * @param header Header to write, in front of packet
139 * @param p Packet to write
140 *
141 */
142 void Write(uint32_t tsSec, uint32_t tsUsec, const Header& header, Ptr<const Packet> p);
143
144 /**
145 * @brief Read next packet from file
146 *
147 * @param data [out] Data buffer
148 * @param maxBytes Allocated data buffer size
149 * @param tsSec [out] Packet timestamp, seconds
150 * @param tsUsec [out] Packet timestamp, microseconds
151 * @param inclLen [out] Included length
152 * @param origLen [out] Original length
153 * @param readLen [out] Number of bytes read
154 *
155 */
156 void Read(uint8_t* const data,
157 uint32_t maxBytes,
158 uint32_t& tsSec,
159 uint32_t& tsUsec,
160 uint32_t& inclLen,
161 uint32_t& origLen,
162 uint32_t& readLen);
163
164 /**
165 * @brief Get the swap mode of the file.
166 *
167 * Pcap files use a magic number that is overloaded to identify both the
168 * format of the file itself and the byte ordering of the file. The magic
169 * number (and all data) is written into the file according to the native
170 * byte ordering of the writing system. If a reading application reads
171 * the magic number identically (for example 0xa1b2c3d4) then no byte
172 * swapping is required to correctly interpret the file data. If the reading
173 * application sees the magic number is byte swapped (for example 0xd4c3b2a1)
174 * then it knows that it needs to byteswap appropriate fields in the format.
175 *
176 * GetSWapMode returns a value indicating whether or not the fields are being
177 * byteswapped. Used primarily for testing the class itself, but may be
178 * useful as a flag indicating a difference in endianness of the writing
179 * system.
180 *
181 * @returns swap mode of the file
182 */
183 bool GetSwapMode();
184
185 /**
186 * @brief Get the nanosecond mode of the file.
187 *
188 * @returns true if the packet timestamps in the PCAP
189 * file have nanosecond resolution.
190 */
191 bool IsNanoSecMode();
192
193 /**
194 * @brief Returns the magic number of the pcap file as defined by the magic_number
195 * field in the pcap global header.
196 *
197 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
198 *
199 * @returns magic number
200 */
202
203 /**
204 * @brief Returns the major version of the pcap file as defined by the version_major
205 * field in the pcap global header.
206 *
207 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
208 *
209 * @returns major version
210 */
211 uint16_t GetVersionMajor();
212
213 /**
214 * @brief Returns the minor version of the pcap file as defined by the version_minor
215 * field in the pcap global header.
216 *
217 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
218 *
219 * @returns minor version
220 */
221 uint16_t GetVersionMinor();
222
223 /**
224 * @brief Returns the time zone offset of the pcap file as defined by the thiszone
225 * field in the pcap global header.
226 *
227 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
228 *
229 * @returns time zone offset
230 */
232
233 /**
234 * @brief Returns the accuracy of timestamps field of the pcap file as defined
235 * by the sigfigs field in the pcap global header.
236 *
237 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
238 *
239 * @returns accuracy of timestamps
240 */
242
243 /**
244 * @brief Returns the max length of saved packets field of the pcap file as
245 * defined by the snaplen field in the pcap global header.
246 *
247 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
248 *
249 * @returns max length of saved packets field
250 */
252
253 /**
254 * @brief Returns the data link type field of the pcap file as defined by the
255 * network field in the pcap global header.
256 *
257 * See http://wiki.wireshark.org/Development/LibpcapFileFormat
258 *
259 * @returns data link type field
260 */
262
263 /**
264 * @brief Compare two PCAP files packet-by-packet
265 *
266 * @param f1 First PCAP file name
267 * @param f2 Second PCAP file name
268 * @param sec [out] Time stamp of first different packet, seconds. Undefined if files don't
269 * differ.
270 * @param usec [out] Time stamp of first different packet, microseconds. Undefined if files
271 * don't differ.
272 * @param packets [out] Number of first different packet. Total number of parsed packets if
273 * files don't differ.
274 * @param snapLen Snap length (if used)
275 * @return true if files are different, false otherwise
276 */
277 static bool Diff(const std::string& f1,
278 const std::string& f2,
279 uint32_t& sec,
280 uint32_t& usec,
281 uint32_t& packets,
282 uint32_t snapLen = SNAPLEN_DEFAULT);
283
284 private:
285 /**
286 * @brief Pcap file header
287 */
289 {
290 uint32_t m_magicNumber; //!< Magic number identifying this as a pcap file
291 uint16_t
292 m_versionMajor; //!< Major version identifying the version of pcap used in this file
293 uint16_t
294 m_versionMinor; //!< Minor version identifying the version of pcap used in this file
295 int32_t m_zone; //!< Time zone correction to be applied to timestamps of packets
296 uint32_t m_sigFigs; //!< Unused by pretty much everybody
297 uint32_t m_snapLen; //!< Maximum length of packet data stored in records
298 uint32_t m_type; //!< Data link type of packet data
299 };
300
301 /**
302 * @brief Pcap record header
303 */
305 {
306 uint32_t m_tsSec; //!< seconds part of timestamp
307 uint32_t m_tsUsec; //!< microseconds part of timestamp (nsecs for PCAP_NSEC_MAGIC)
308 uint32_t m_inclLen; //!< number of octets of packet saved in file
309 uint32_t m_origLen; //!< actual length of original packet
310 };
311
312 /**
313 * @brief Swap a value byte order
314 * @param val the value
315 * @returns the value with byte order swapped
316 */
317 uint8_t Swap(uint8_t val);
318 /**
319 * @brief Swap a value byte order
320 * @param val the value
321 * @returns the value with byte order swapped
322 */
323 uint16_t Swap(uint16_t val);
324 /**
325 * @brief Swap a value byte order
326 * @param val the value
327 * @returns the value with byte order swapped
328 */
330 /**
331 * @brief Swap the byte order of a Pcap file header
332 * @param from original file header
333 * @param to swapped file header
334 */
335 void Swap(PcapFileHeader* from, PcapFileHeader* to);
336 /**
337 * @brief Swap the byte order of a Pcap record header
338 * @param from original record header
339 * @param to swapped record header
340 */
341 void Swap(PcapRecordHeader* from, PcapRecordHeader* to);
342
343 /**
344 * @brief Write a Pcap file header
345 */
346 void WriteFileHeader();
347 /**
348 * @brief Write a Pcap packet header
349 *
350 * The pcap header has a fixed length of 24 bytes. The last 4 bytes
351 * represent the link-layer type
352 *
353 * @param tsSec Time stamp (seconds part)
354 * @param tsUsec Time stamp (microseconds part)
355 * @param totalLen total packet length
356 * @returns the length of the packet to write in the Pcap file
357 */
358 uint32_t WritePacketHeader(uint32_t tsSec, uint32_t tsUsec, uint32_t totalLen);
359
360 /**
361 * @brief Read and verify a Pcap file header
362 */
364
365 std::string m_filename; //!< file name
366 std::fstream m_file; //!< file stream
367 PcapFileHeader m_fileHeader; //!< file header
368 bool m_swapMode; //!< swap mode
369 bool m_nanosecMode; //!< nanosecond timestamp mode
370};
371
372} // namespace ns3
373
374#endif /* PCAP_FILE_H */
Protocol header serialization and deserialization.
Definition header.h:33
A class representing a pcap file.
Definition pcap-file.h:32
bool IsNanoSecMode()
Get the nanosecond mode of the file.
Definition pcap-file.cc:144
void Close()
Close the underlying file.
Definition pcap-file.cc:81
static bool Diff(const std::string &f1, const std::string &f2, uint32_t &sec, uint32_t &usec, uint32_t &packets, uint32_t snapLen=SNAPLEN_DEFAULT)
Compare two PCAP files packet-by-packet.
Definition pcap-file.cc:526
void Open(const std::string &filename, std::ios::openmode mode)
Create a new pcap file or open an existing pcap file.
Definition pcap-file.cc:320
uint32_t GetDataLinkType()
Returns the data link type field of the pcap file as defined by the network field in the pcap global ...
Definition pcap-file.cc:130
bool m_swapMode
swap mode
Definition pcap-file.h:368
void Read(uint8_t *const data, uint32_t maxBytes, uint32_t &tsSec, uint32_t &tsUsec, uint32_t &inclLen, uint32_t &origLen, uint32_t &readLen)
Read next packet from file.
Definition pcap-file.cc:468
uint32_t GetMagic()
Returns the magic number of the pcap file as defined by the magic_number field in the pcap global hea...
Definition pcap-file.cc:88
uint16_t GetVersionMajor()
Returns the major version of the pcap file as defined by the version_major field in the pcap global h...
Definition pcap-file.cc:95
std::string m_filename
file name
Definition pcap-file.h:365
uint16_t GetVersionMinor()
Returns the minor version of the pcap file as defined by the version_minor field in the pcap global h...
Definition pcap-file.cc:102
PcapFileHeader m_fileHeader
file header
Definition pcap-file.h:367
void Clear()
Clear all state bits of the underlying iostream.
Definition pcap-file.cc:74
uint32_t WritePacketHeader(uint32_t tsSec, uint32_t tsUsec, uint32_t totalLen)
Write a Pcap packet header.
Definition pcap-file.cc:402
void Init(uint32_t dataLinkType, uint32_t snapLen=SNAPLEN_DEFAULT, int32_t timeZoneCorrection=ZONE_DEFAULT, bool swapMode=false, bool nanosecMode=false)
Initialize the pcap file associated with this object.
Definition pcap-file.cc:340
void Write(uint32_t tsSec, uint32_t tsUsec, const uint8_t *const data, uint32_t totalLen)
Write next packet to file.
Definition pcap-file.cc:433
bool Eof() const
Definition pcap-file.cc:67
bool Fail() const
Definition pcap-file.cc:60
uint32_t GetSnapLen()
Returns the max length of saved packets field of the pcap file as defined by the snaplen field in the...
Definition pcap-file.cc:123
bool GetSwapMode()
Get the swap mode of the file.
Definition pcap-file.cc:137
static const int32_t ZONE_DEFAULT
Time zone offset for current location.
Definition pcap-file.h:34
bool m_nanosecMode
nanosecond timestamp mode
Definition pcap-file.h:369
static const uint32_t SNAPLEN_DEFAULT
Default value for maximum octets to save per packet.
Definition pcap-file.h:35
int32_t GetTimeZoneOffset()
Returns the time zone offset of the pcap file as defined by the thiszone field in the pcap global hea...
Definition pcap-file.cc:109
std::fstream m_file
file stream
Definition pcap-file.h:366
void ReadAndVerifyFileHeader()
Read and verify a Pcap file header.
Definition pcap-file.cc:241
void WriteFileHeader()
Write a Pcap file header.
Definition pcap-file.cc:196
uint32_t GetSigFigs()
Returns the accuracy of timestamps field of the pcap file as defined by the sigfigs field in the pcap...
Definition pcap-file.cc:116
uint8_t Swap(uint8_t val)
Swap a value byte order.
Definition pcap-file.cc:151
Smart pointer class similar to boost::intrusive_ptr.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
uint8_t data[writeSize]
uint32_t m_magicNumber
Magic number identifying this as a pcap file.
Definition pcap-file.h:290
uint32_t m_sigFigs
Unused by pretty much everybody.
Definition pcap-file.h:296
int32_t m_zone
Time zone correction to be applied to timestamps of packets.
Definition pcap-file.h:295
uint16_t m_versionMajor
Major version identifying the version of pcap used in this file.
Definition pcap-file.h:292
uint32_t m_type
Data link type of packet data.
Definition pcap-file.h:298
uint32_t m_snapLen
Maximum length of packet data stored in records.
Definition pcap-file.h:297
uint16_t m_versionMinor
Minor version identifying the version of pcap used in this file.
Definition pcap-file.h:294
uint32_t m_inclLen
number of octets of packet saved in file
Definition pcap-file.h:308
uint32_t m_tsUsec
microseconds part of timestamp (nsecs for PCAP_NSEC_MAGIC)
Definition pcap-file.h:307
uint32_t m_tsSec
seconds part of timestamp
Definition pcap-file.h:306
uint32_t m_origLen
actual length of original packet
Definition pcap-file.h:309