NAME

File::PCAP::Reader - read PCAP files with pure Perl

VERSION

Version v0.1.0

SYNOPSIS

This module reads PCAP files that are written with tcpdump.

    use File::PCAP::Reader;

    my $fpr = File::PCAP::Reader->new( $fname );

    my $gh = $fpr->global_header();

    my $tsec = $fpr->next_packet();

SUBROUTINES/METHODS

new( $fname )

Open a PCAP file and read it's global header.

global_header()

Return a reference to a hash that contains the data of the global header of the PCAP file.

This hash contains the following keys:

magic_number

The magic number 0xa1b2c3d4 or 0xa1b23c4d for nanosecond-resolution files.

At the moment this version of the library does not handle files from architectures with a different byte ordering.

version_major

The major version number.

version_minor

The minor version number.

thiszone

The GMT to local time correction.

sigfigs

The accuracy of the timestamps in the file.

snaplen

The maximum length of the captured packets in octets.

network

The data link type of the packets in this file.

Returns either the link type name of the global header field network or its numerical value.

next_packet()

Read the next datagram record in the PCAP file.

Returns a hash reference containing the data of the next packet or nothing at the end of the PCAP file.

This hash contains the following keys

ts_sec

The date and time when this packet was captured. This value is in seconds since January 1, 1970 00:00:00 GMT.

ts_usec

The microseconds when this packet was captured as an offset to ts_sec.

incl_len

The number of octets of packet data saved in the file.

orig_len

The length of the packet as it appeared on the network when it was captured.

buf

The actual packet data as a blob. This buffer should contain at least inc_len bytes.

You may want to use it like this:

  while(my $np = $fpr->next_packet()) {
    # ... do something with $np
  }

DIAGNOSTICS

Need a filename to read PCAP data from

You need to specify a filename with the constructor.

Can't open file '$fname' for reading

The file you specified with $fname is not readable.

Don't know how to handle file with magic number 0xaabbccdd

The magic number in the first 4 bytes of a PCAP file is 0xa1b2c3d4. This number is used to detect the file format itself and the byte ordering.

At the moment this module just handles PCAP files with the same byte order as the computer this program is running on.

Can't handle file version $vmajor.$vminor

At the moment this module just handles PCAP file version 2.4.

Can't read packet data from file '$!'

There was a problem reading the packet data from the file.

Reached EOF before reading packet header!

The file reached EOF while trying to read the last packet header.

This may be a hint to a shortened file.

Reached EOF before reading packet buffer!

The file reached EOF while trying to read the last packet buffer.

This may be a hint to a shortened file.

AUTHOR

Mathias Weidner, <mamawe at cpan.org>

BUGS

Please report any bugs or feature requests to bug-file-pcap at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-PCAP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc File::PCAP::Reader

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2017 Mathias Weidner.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.