Net::F...Online(3pm)

💖 Net::Frame::Dump::Online ✨

hiii bestie 🫶 so this is the manual page for Net::Frame::Dump::Online — it lives in the perl docs, section 3pm, under "User Contributed Perl Documentation" (yes that's the whole vibe of the manual name, iykyk). Anyway. Snacks out, brain on, let's go 💅

---

🌸 NAME

Net::Frame::Dump::Online — a tcpdump-like implementation, online mode. that's the whole name. iconic of it honestly ✨

---

🦋 SYNOPSIS

okay so first up, the absolute simplest thing you can do — just make a Dump object and let it cook:

use Net::Frame::Dump::Online;

#
# Simply create a Dump object
#
my $oDump = Net::Frame::Dump::Online->new(
   dev => 'eth0',
);

$oDump->start;

# Gather frames
while (1) {
   if (my $f = $oDump->next) {
      my $raw            = $f->{raw};
      my $firstLayerType = $f->{firstLayer};
      my $timestamp      = $f->{timestamp};
   }
}

$oDump->stop;

and then there's the on-event loop era, if you'd rather have a callback do the work instead of a while (1) staring at you 😭:

#
# Create a Dump object, using on-event loop
#
sub callOnRecv {
   my ($h, $data) = @_;
   print "Data: $data\n";
   my $oSimple = Net::Frame::Simple->newFromDump($h);
   print $oSimple->print."\n";
}

my $oDumpEvent = Net::Frame::Dump::Online->new(
   dev         => 'eth0',
   onRecv      => \&callOnRecv,
   onRecvCount => 1,
   onRecvData  => 'test',
);

# Will block here, until $onRecvCount packets read, or a stop() call has
# been performed.
$oDumpEvent->start;

and here are all the default parameters you get when you create one, laid out exactly as the module does it, no cap 🎀:

#
# Default parameters on creation
#
my $oDumpDefault = Net::Frame::Dump::Online->new(
   dev            => undef,
   timeoutOnNext  => 3,
   timeout        => 0,
   promisc        => 0,
   unlinkOnStop   => 1,
   file           => "netframe-tmp-$$.$int.pcap",
   filter         => '',
   overwrite      => 0,
   isRunning      => 0,
   keepTimestamp  => 0,
   onRecvCount    => -1,
   frames         => [],
);

---

🌈 DESCRIPTION

this module implements a tcpdump-like program, for live capture from networks. like, actually live. from the wire. it's giving main character energy fr fr 🔥

---

👑 ATTRIBUTES

• dev — the network interface you want to listen on. There is no default value. you gotta say it, bestie.
• timeoutOnNext — every single time you call the next method, an internal counter gets updated. that counter is basically telling you "hey, you haven't received any data in timeoutOnNext seconds." and when a timeout does happen, timeout gets set to true. ⏰
• timeout — when timeoutOnNext seconds has been reached, this variable gets set to true, and it never resets. if you want it reset, go look at timeoutReset. periodt.
• snaplen — if you want to capture a different snaplen, set it to a number. Defaults to 1514. 📏
• promisc — by default, the interface is not put into promiscuous mode. set this parameter to true if that's what you want. live your truth 💅
• unlinkOnStop — when you call the stop method, the generated .pcap file gets removed — unless you set this parameter to a false value. 🗑️
• onRecv — if you put a reference to a sub in here, it will be called every time a packet is received on the interface. go check the SYNOPSIS for an example of how that looks. 📞
• onRecvData — this parameter stores extra data that gets passed along to the onRecv callback.
• onRecvCount — by default it's set to read packets that reach your network interface forever. set it to a positive value and it'll only read onRecvCount frames. 🛑

✨ the following are inherited attributes ✨

• file — name of the generated .pcap file. peek at the SYNOPSIS for the default name.
• filter — the pcap filter to use. Defaults to no filter at all.
• overwrite — overwrites a .pcap file that already exists. Defaults to not doing that.
• firstLayer — stores info about the first layer type contained in a read frame. this attribute only gets filled after you call the start method.
• isRunning — returns true if a call to start has happened, false otherwise — or if a call to stop has happened.
• keepTimestamp — sometimes, when frames get captured and saved to a .pcap file, the timestamps suck 😭 like, you send a frame, you receive the reply, but your request appears to have been sent after the reply. wild. so to fix that, you can use Net::Frame::Dump's own timestamping system. the default is 0. set it manually to 1 if you need the original .pcap frame timestamps.

---

💅 METHODS

• new
• new (hash) — the object constructor. you can pass attributes in and they'll overwrite the defaults. check the SYNOPSIS for the default values. 🎁
• start — call this method when you want to start reading frames from the network. 🚀
• stop — call this method when you want to stop reading frames from the network. 🛑
• next — returns the next captured frame; undef if nothing's waiting. every time you call this method, a comparison happens to see if no frame has been captured during timeoutOnNext number of seconds. if that's the case, the timeout attribute is set to 1 to reflect the pending timeout. 👀
• store (Net::Frame::Simple object) — this method stores the Net::Frame::Simple object you pass as a single parameter internally, sorted. the getKey methods, which are implemented in various Net::Frame::Layer objects, get used to efficiently retrieve frames (via the getKeyReverse method).

basically, it's used to make the recv method (from Net::Frame::Simple) quickly retrieve the reply frame for a request frame. ⚡

• getFramesFor (Net::Frame::Simple object) — this returns an array of possible reply frames for the Net::Frame::Simple object you specified. for example, reply frames for a UDP probe will be all the frames that have the same source port and destination port as the request. 🎯
• flush — flushes stored frames — the ones that got stored via the store method. 🧹
• timeoutReset — resets the internal timeout state (the timeout attribute). ♻️
• getStats — tries to get packet statistics on an open descriptor. returns a reference to a hash that has the following fields: ps_recv, ps_drop, ps_ifdrop. 📊
• isFather
• isSon — these methods tell you whether your current process is, respectively, the father or the son process of the Net::Frame::Dump::Online object. family drama, but make it fork 🧬

---

🦋 SEE ALSO

Net::Frame::Dump

---

🎀 AUTHOR

Patrice <GomoR> Auffret

---

⭐ COPYRIGHT AND LICENSE

Copyright (c) 2006-2020, Patrice <GomoR> Auffret

You may distribute this module under the terms of the Artistic license. See LICENSE.Artistic file in the source distribution archive.

---

okay that's the whole page bestie, you ate it 💖 this was Net::Frame::Dump::Online(3pm) as documented by the User Contributed Perl Documentation, running under perl v5.36.0 and dated 2022-11-19 — go capture some frames, mwah 🫶✨👑