1Pcap(3)               User Contributed Perl Documentation              Pcap(3)
2
3
4

NAME

6       Net::Pcap - Interface to the pcap(3) LBL packet capture library
7

VERSION

9       Version 0.21
10

SYNOPSIS

12           use Net::Pcap;
13
14           my $err = '';
15           my $dev = pcap_lookupdev(\$err);  # find a device
16
17           # open the device for live listening
18           my $pcap = pcap_open_live($dev, 1024, 1, 0, \$err);
19
20           # loop over next 10 packets
21           pcap_loop($pcap, 10, \&process_packet, "just for the demo");
22
23           # close the device
24           pcap_close($pcap);
25
26           sub process_packet {
27               my ($user_data, $header, $packet) = @_;
28               # do something ...
29           }
30

DESCRIPTION

32       "Net::Pcap" is a Perl binding to the LBL pcap(3) library and its Win32
33       counterpart, the WinPcap library. Pcap (packet capture) is a portable
34       API to capture network packet: it allows applications to capture
35       packets at link-layer, bypassing the normal protocol stack. It also
36       provides features like kernel-level packet filtering and access to
37       internal statistics.
38
39       Common applications include network statistics collection, security
40       monitoring, network debugging, etc.
41

NOTES

43   Signals handling
44       Since version 5.7.3, Perl uses a mechanism called "deferred signals" to
45       delay signals delivery until "safe" points in the interpreter.  See
46       "Deferred Signals (Safe Signals)" in perlipc for a detailed
47       explanation.
48
49       Since "Net::Pcap" version 0.08, released in October 2005, the module
50       modified the internal variable "PL_signals" to re-enable immediate
51       signals delivery in Perl 5.8 and later within some XS functions (CPAN-
52       RT #6320). However, it can create situations where the Perl interpreter
53       is less stable and can crash (CPAN-RT #43308). Therefore, as of version
54       0.17, "Net::Pcap" no longer modifies "PL_signals" by itself, but
55       provides facilities so the user has full control of how signals are
56       delivered.
57
58       First, the pcap_perl_settings() function allows one to select how
59       signals are handled:
60
61           pcap_perl_settings(PERL_SIGNALS_UNSAFE);
62           pcap_loop($pcap, 10, \&process_packet, "");
63           pcap_perl_settings(PERL_SIGNALS_SAFE);
64
65       Then, to easily make code interruptable, "Net::Pcap" provides the
66       "UNSAFE_SIGNALS" pseudo-bloc:
67
68           UNSAFE_SIGNALS {
69               pcap_loop($pcap, 10, \&process_packet, "");
70           };
71
72       (Stolen from Rafael Garcia-Suarez's "Perl::Unsafe::Signals")
73

EXPORTS

75       "Net::Pcap" supports the following "Exporter" tags:
76
77       •   ":bpf" exports a few BPF related constants:
78
79               BPF_ALIGNMENT  BPF_MAJOR_VERSION  BPF_MAXBUFSIZE  BPF_MAXINSNS
80               BPF_MEMWORDS  BPF_MINBUFSIZE  BPF_MINOR_VERSION  BPF_RELEASE
81
82       •   ":datalink" exports the data link types macros:
83
84               DLT_AIRONET_HEADER  DLT_APPLE_IP_OVER_IEEE1394  DLT_ARCNET
85               DLT_ARCNET_LINUX  DLT_ATM_CLIP  DLT_ATM_RFC1483  DLT_AURORA
86               DLT_AX25  DLT_CHAOS  DLT_CHDLC  DLT_CISCO_IOS  DLT_C_HDLC
87               DLT_DOCSIS  DLT_ECONET  DLT_EN10MB  DLT_EN3MB  DLT_ENC  DLT_FDDI
88               DLT_FRELAY  DLT_HHDLC  DLT_IBM_SN  DLT_IBM_SP  DLT_IEEE802
89               DLT_IEEE802_11  DLT_IEEE802_11_RADIO DLT_IEEE802_11_RADIO_AVS
90               DLT_IPFILTER  DLT_IP_OVER_FC  DLT_JUNIPER_ATM1 DLT_JUNIPER_ATM2
91               DLT_JUNIPER_ES  DLT_JUNIPER_GGSN  DLT_JUNIPER_MFR DLT_JUNIPER_MLFR
92               DLT_JUNIPER_MLPPP  DLT_JUNIPER_MONITOR  DLT_JUNIPER_SERVICES
93               DLT_LINUX_IRDA  DLT_LINUX_SLL  DLT_LOOP  DLT_LTALK  DLT_NULL
94               DLT_OLD_PFLOG  DLT_PCI_EXP  DLT_PFLOG  DLT_PFSYNC  DLT_PPP
95               DLT_PPP_BSDOS  DLT_PPP_ETHER  DLT_PPP_SERIAL  DLT_PRISM_HEADER
96               DLT_PRONET  DLT_RAW  DLT_RIO  DLT_SLIP  DLT_SLIP_BSDOS  DLT_SUNATM
97               DLT_SYMANTEC_FIREWALL  DLT_TZSP  DLT_USER0  DLT_USER1  DLT_USER2
98               DLT_USER3  DLT_USER4  DLT_USER5  DLT_USER6  DLT_USER7  DLT_USER8
99               DLT_USER9  DLT_USER10  DLT_USER11  DLT_USER12  DLT_USER13
100               DLT_USER14  DLT_USER15
101
102       •   ":pcap" exports the following "pcap" constants:
103
104               PCAP_ERRBUF_SIZE    PCAP_IF_LOOPBACK
105               PCAP_VERSION_MAJOR  PCAP_VERSION_MINOR
106
107       •   ":mode" exports the following constants:
108
109               MODE_CAPT  MODE_MON  MODE_STAT
110
111       •   ":openflag" exports the following constants:
112
113               OPENFLAG_PROMISCUOUS  OPENFLAG_DATATX_UDP  OPENFLAG_NOCAPTURE_RPCAP
114
115       •   ":source" exports the following constants:
116
117               PCAP_SRC_FILE  PCAP_SRC_IFLOCAL  PCAP_SRC_IFREMOTE
118
119       •   ":sample" exports the following constants:
120
121               PCAP_SAMP_NOSAMP  PCAP_SAMP_1_EVERY_N  PCAP_SAMP_FIRST_AFTER_N_MS
122
123       •   ":rpcap" exports the following constants:
124
125               RMTAUTH_NULL  RMTAUTH_PWD
126
127       •   ":functions" short names of the functions (without the "pcap_"
128           prefix) for those which would not cause a clash with an already
129           defined name.  Namely, the following functions are not available in
130           short form: open(), close(), next(), dump(), file(), fileno().
131           Using these short names is now discouraged, and may be removed in
132           the future.
133
134       By default, this module exports the symbols from the ":datalink" and
135       ":pcap" tags, and all the functions, with the same names as the C
136       library.
137

FUNCTIONS

139       All functions defined by "Net::Pcap" are direct mappings to the libpcap
140       functions.  Consult the pcap(3) documentation and source code for more
141       information.
142
143       Arguments that change a parameter, for example pcap_lookupdev(), are
144       passed that parameter as a reference.  This is to retain compatibility
145       with previous versions of "Net::Pcap".
146
147   Lookup functions
148       pcap_lookupdev(\$err)
149           Returns the name of a network device that can be used with
150           pcap_open_live() function.  On error, the $err parameter is filled
151           with an appropriate error message else it is undefined.
152
153           Example
154
155               $dev = pcap_lookupdev();
156
157       pcap_findalldevs(\%devinfo, \$err)
158           Returns a list of all network device names that can be used with
159           pcap_open_live() function.  On error, the $err parameter is filled
160           with an appropriate error message else it is undefined.
161
162           Example
163
164               @devs = pcap_findalldevs(\%devinfo, \$err);
165               for my $dev (@devs) {
166                   print "$dev : $devinfo{$dev}\n"
167               }
168
169           Note
170               For backward compatibility reasons, this function can also be
171               called using the following signatures:
172
173                   @devs = pcap_findalldevs(\$err);
174
175                   @devs = pcap_findalldevs(\$err, \%devinfo);
176
177               The first form was introduced by Marco Carnut in "Net::Pcap"
178               version 0.05 and kept intact in versions 0.06 and 0.07.  The
179               second form was introduced by Jean-Louis Morel for the Windows
180               only, ActivePerl port of "Net::Pcap", in versions 0.04.01 and
181               0.04.02.
182
183               The new syntax has been introduced for consistency with the
184               rest of the Perl API and the C API of libpcap(3), where $err is
185               always the last argument.
186
187       pcap_lookupnet($dev, \$net, \$mask, \$err)
188           Determine the network number and netmask for the device specified
189           in $dev.  The function returns 0 on success and sets the $net and
190           $mask parameters with values.  On failure it returns -1 and the
191           $err parameter is filled with an appropriate error message.
192
193   Packet capture functions
194       pcap_open_live($dev, $snaplen, $promisc, $to_ms, \$err)
195           Returns a packet capture descriptor for looking at packets on the
196           network.  The $dev parameter specifies which network interface to
197           capture packets from.  The $snaplen and $promisc parameters specify
198           the maximum number of bytes to capture from each packet, and
199           whether to put the interface into promiscuous mode, respectively.
200           The $to_ms parameter specifies a read timeout in milliseconds.  The
201           packet descriptor will be undefined if an error occurs, and the
202           $err parameter will be set with an appropriate error message.
203
204           Example
205
206               $dev = pcap_lookupdev();
207               $pcap = pcap_open_live($dev, 1024, 1, 0, \$err)
208                   or die "Can't open device $dev: $err\n";
209
210       pcap_open_dead($linktype, $snaplen)
211           Creates and returns a new packet descriptor to use when calling the
212           other functions in "libpcap". It is typically used when just using
213           "libpcap" for compiling BPF code.
214
215           Example
216
217               $pcap = pcap_open_dead(0, 1024);
218
219       pcap_open_offline($filename, \$err)
220           Return a packet capture descriptor to read from a previously
221           created "savefile".  The returned descriptor is undefined if there
222           was an error and in this case the $err parameter will be filled.
223           Savefiles are created using the "pcap_dump_*" commands.
224
225           Example
226
227               $pcap = pcap_open_offline($dump, \$err)
228                   or die "Can't read '$dump': $err\n";
229
230       pcap_loop($pcap, $count, \&callback, $user_data)
231           Read $count packets from the packet capture descriptor $pcap and
232           call the perl function &callback with an argument of $user_data.
233           If $count is negative, then the function loops forever or until an
234           error occurs. Returns 0 if $count is exhausted, -1 on error, and -2
235           if the loop terminated due to a call to pcap_breakloop() before any
236           packets were processed.
237
238           The callback function is also passed packet header information and
239           packet data like so:
240
241               sub process_packet {
242                   my ($user_data, $header, $packet) = @_;
243
244                   ...
245               }
246
247           The header information is a reference to a hash containing the
248           following fields.
249
250           •   "len" - the total length of the packet.
251
252           •   "caplen" - the actual captured length of the packet data.  This
253               corresponds to the snapshot length parameter passed to
254               open_live().
255
256           •   "tv_sec" - seconds value of the packet timestamp.
257
258           •   "tv_usec" - microseconds value of the packet timestamp.
259
260           Example
261
262               pcap_loop($pcap, 10, \&process_packet, "user data");
263
264               sub process_packet {
265                   my ($user_data, $header, $packet) = @_;
266                   # ...
267               }
268
269       pcap_breakloop($pcap)
270           Sets a flag  that will force pcap_dispatch() or pcap_loop() to
271           return rather than looping; they will return the number of packets
272           that have been processed so far, or -2 if no packets have been
273           processed so far.
274
275           This routine is safe to use inside a signal handler on UNIX or a
276           console control handler on Windows, as it merely sets a flag that
277           is checked within the loop.
278
279           Please see the section on pcap_breakloop() in pcap(3) for more
280           information.
281
282       pcap_close($pcap)
283           Close the packet capture device associated with the descriptor
284           $pcap.
285
286       pcap_dispatch($pcap, $count, \&callback, $user_data)
287           Collect $count packets and process them with callback function
288           &callback.  if $count is -1, all packets currently buffered are
289           processed.  If $count is 0, process all packets until an error
290           occurs.
291
292       pcap_next($pcap, \%header)
293           Return the next available packet on the interface associated with
294           packet descriptor $pcap.  Into the %header hash is stored the
295           received packet header.  If not packet is available, the return
296           value and header is undefined.
297
298       pcap_next_ex($pcap, \%header, \$packet)
299           Reads the next available packet on the interface associated with
300           packet descriptor $pcap, stores its header in "\%header" and its
301           data in "\$packet" and returns a success/failure indication:
302
303           •   1 means that the packet was read without problems;
304
305           •   0 means that packets are being read from a live capture, and
306               the timeout expired;
307
308           •   -1 means that an error occurred while reading the packet;
309
310           •   -2 packets are being read from a dump file, and there are no
311               more packets to read from the savefile.
312
313       pcap_compile($pcap, \$filter, $filter_str, $optimize, $netmask)
314           Compile the filter string contained in $filter_str and store it in
315           $filter.  A description of the filter language can be found in the
316           libpcap source code, or the manual page for tcpdump(8) .  The
317           filter is optimized if the $optimize variable is true.  The netmask
318           of the network device must be specified in the $netmask parameter.
319           The function returns 0 if the compilation was successful, or -1 if
320           there was a problem.
321
322       pcap_compile_nopcap($snaplen, $linktype, \$filter, $filter_str,
323       $optimize, $netmask)
324           Similar to compile() except that instead of passing a $pcap
325           descriptor, one passes $snaplen and $linktype directly. Returns -1
326           if there was an error, but the error message is not available.
327
328       pcap_setfilter($pcap, $filter)
329           Associate the compiled filter stored in $filter with the packet
330           capture descriptor $pcap.
331
332       pcap_freecode($filter)
333           Used to free the allocated memory used by a compiled filter, as
334           created by pcap_compile().
335
336       pcap_offline_filter($filter, \%header, $packet)
337           Check whether $filter matches the packet described by header
338           %header and packet data $packet. Returns true if the packet
339           matches.
340
341       pcap_setnonblock($pcap, $mode, \$err)
342           Set the non-blocking mode of a live capture descriptor, depending
343           on the value of $mode (zero to activate and non-zero to
344           deactivate). It has no effect on offline descriptors. If there is
345           an error, it returns -1 and sets $err.
346
347           In non-blocking mode, an attempt to read from the capture
348           descriptor with pcap_dispatch() will, if no packets are currently
349           available to be read, return 0  immediately rather than blocking
350           waiting for packets to arrive.  pcap_loop() and pcap_next() will
351           not work in non-blocking mode.
352
353       pcap_getnonblock($pcap, \$err)
354           Returns the non-blocking state of the capture descriptor $pcap.
355           Always returns 0 on savefiles. If there is an error, it returns -1
356           and sets $err.
357
358   Savefile commands
359       pcap_dump_open($pcap, $filename)
360           Open a savefile for writing and return a descriptor for doing so.
361           If $filename is "-" data is written to standard output.  On error,
362           the return value is undefined and pcap_geterr() can be used to
363           retrieve the error text.
364
365       pcap_dump($dumper, \%header, $packet)
366           Dump the packet described by header %header and packet data $packet
367           to the savefile associated with $dumper.  The packet header has the
368           same format as that passed to the pcap_loop() callback.
369
370           Example
371
372               my $dump_file = 'network.dmp';
373               my $dev = pcap_lookupdev();
374               my $pcap = pcap_open_live($dev, 1024, 1, 0, \$err);
375
376               my $dumper = pcap_dump_open($pcap, $dump_file);
377               pcap_loop($pcap, 10, \&process_packet, '');
378               pcap_dump_close($dumper);
379
380               sub process_packet {
381                   my ($user_data, $header, $packet) = @_;
382                   pcap_dump($dumper, $header, $packet);
383               }
384
385       pcap_dump_file($dumper)
386           Returns the filehandle associated with a savefile opened with
387           pcap_dump_open().
388
389       pcap_dump_flush($dumper)
390           Flushes the output buffer to the corresponding save file, so that
391           any packets written with pcap_dump() but not yet written to the
392           save file will be written. Returns -1 on error, 0 on success.
393
394       pcap_dump_close($dumper)
395           Close the savefile associated with the descriptor $dumper.
396
397   Status functions
398       pcap_datalink($pcap)
399           Returns the link layer type associated with the given pcap
400           descriptor.
401
402           Example
403
404               $linktype = pcap_datalink($pcap);
405
406       pcap_set_datalink($pcap, $linktype)
407           Sets the data link type of the given pcap descriptor to the type
408           specified by $linktype. Returns -1 on failure.
409
410       pcap_datalink_name_to_val($name)
411           Translates a data link type name, which is a "DLT_" name with the
412           "DLT_" part removed, to the corresponding data link type value. The
413           translation is case-insensitive. Returns -1 on failure.
414
415           Example
416
417               $linktype = pcap_datalink_name_to_val('LTalk');  # returns DLT_LTALK
418
419       pcap_datalink_val_to_name($linktype)
420           Translates a data link type value to the corresponding data link
421           type name.
422
423           Example
424
425               $name = pcap_datalink_val_to_name(DLT_LTALK);  # returns 'LTALK'
426
427       pcap_datalink_val_to_description($linktype)
428           Translates a data link type value to a short description of that
429           data link type.
430
431           Example
432
433               $descr = pcap_datalink_val_to_description(DLT_LTALK);  # returns 'Localtalk'
434
435       pcap_snapshot($pcap)
436           Returns the snapshot length (snaplen) specified in the call to
437           pcap_open_live().
438
439       pcap_is_swapped($pcap)
440           This function returns true if the endianness of the currently open
441           savefile is different from the endianness of the machine.
442
443       pcap_major_version($pcap)
444           Return the major version number of the pcap library used to write
445           the currently open savefile.
446
447       pcap_minor_version($pcap)
448           Return the minor version of the pcap library used to write the
449           currently open savefile.
450
451       pcap_stats($pcap, \%stats)
452           Returns a hash containing information about the status of packet
453           capture device $pcap.  The hash contains the following fields.
454
455           This function is supported only on live captures, not on savefiles;
456           no statistics are stored in savefiles, so no statistics are
457           available when reading from a savefile.
458
459           •   "ps_recv" - the number of packets received by the packet
460               capture software.
461
462           •   "ps_drop" - the number of packets dropped by the packet capture
463               software.
464
465           •   "ps_ifdrop" - the number of packets dropped by the network
466               interface.
467
468       pcap_file($pcap)
469           Returns the filehandle associated with a savefile opened with
470           pcap_open_offline() or "undef" if the device was opened with
471           pcap_open_live().
472
473       pcap_fileno($pcap)
474           Returns the file number of the network device opened with
475           pcap_open_live().
476
477       pcap_get_selectable_fd($pcap)
478           Returns, on Unix, a file descriptor number for a file descriptor on
479           which one can do a select() or poll() to wait for it to be possible
480           to read packets without blocking, if such a descriptor exists, or
481           -1, if no such descriptor exists. Some network devices opened with
482           pcap_open_live() do not support select() or poll(), so -1 is
483           returned for those devices.  See pcap(3) for more details.
484
485   Error handling
486       pcap_geterr($pcap)
487           Returns an error message for the last error associated with the
488           packet capture device $pcap.
489
490       pcap_strerror($errno)
491           Returns a string describing error number $errno.
492
493       pcap_perror($pcap, $prefix)
494           Prints the text of the last error associated with descriptor $pcap
495           on standard error, prefixed by $prefix.
496
497   Information
498       pcap_lib_version()
499           Returns the name and version of the "pcap" library the module was
500           linked against.
501
502   Perl specific functions
503       The following functions are specific to the Perl binding of libpcap.
504
505       pcap_perl_settings($setting)
506           Modify internal behaviour of the Perl interpreter.
507
508           •   "PERL_SIGNALS_SAFE", "PERL_SIGNALS_UNSAFE" respectively enable
509               safe or unsafe signals delivery. Returns the previous value of
510               "PL_signals".  See "Signals handling".
511
512               Example:
513
514                   local $SIG{ALRM} = sub { pcap_breakloop() };
515                   alarm 60;
516
517                   pcap_perl_settings(PERL_SIGNALS_UNSAFE);
518                   pcap_loop($pcap, 10, \&process_packet, "");
519                   pcap_perl_settings(PERL_SIGNALS_SAFE);
520
521   WinPcap specific functions
522       The following functions are only available with WinPcap, the Win32 port
523       of the Pcap library.  If a called function is not available, it will
524       cleanly croak().
525
526       pcap_createsrcstr(\$source, $type, $host, $port, $name, \$err)
527           Accepts a set of strings (host name, port, ...), and stores the
528           complete source string according to the new format (e.g.
529           "rpcap://1.2.3.4/eth0") in $source.
530
531           This function is provided in order to help the user creating the
532           source string according to the new format. An unique source string
533           is used in order to make easy for old applications to use the
534           remote facilities.  Think about tcpdump(1), for example, which has
535           only one way to specify the interface on which the capture has to
536           be started. However, GUI-based programs can find more useful to
537           specify hostname, port and interface name separately. In that case,
538           they can use this function to create the source string before
539           passing it to the pcap_open() function.
540
541           Returns 0 if everything is fine, -1 if some errors occurred. The
542           string containing the complete source is returned in the $source
543           variable.
544
545       pcap_parsesrcstr($source, \$type, \$host, \$port, \$name, \$err)
546           Parse the source string and stores the pieces in which the source
547           can be split in the corresponding variables.
548
549           This call is the other way round of pcap_createsrcstr(). It accepts
550           a null-terminated string and it returns the parameters related to
551           the source.  This includes:
552
553           •   the type of the source (file, WinPcap on a remote adapter,
554               WinPcap on local adapter), which is determined by the source
555               prefix ("PCAP_SRC_IF_STRING" and so on);
556
557           •   the host on which the capture has to be started (only for
558               remote captures);
559
560           •   the raw name of the source (file name, name of the remote
561               adapter, name of the local adapter), without the source prefix.
562               The string returned does not include the type of the source
563               itself (i.e. the string returned does not include "file://" or
564               "rpcap://" or such).
565
566           The user can omit some parameters in case it is not interested in
567           them.
568
569           Returns 0 if everything is fine, -1 if some errors occurred. The
570           requested values (host name, network port, type of the source) are
571           returned into the proper variables passed by reference.
572
573       pcap_open($source, $snaplen, $flags, $read_timeout, \$auth, \$err)
574           Open a generic source in order to capture / send (WinPcap only)
575           traffic.
576
577           The pcap_open() replaces all the pcap_open_xxx() functions with a
578           single call.
579
580           This function hides the differences between the different
581           pcap_open_xxx() functions so that the programmer does not have to
582           manage different opening function. In this way, the true open()
583           function is decided according to the source type, which is included
584           into the source string (in the form of source prefix).
585
586           Returns a pointer to a pcap descriptor which can be used as a
587           parameter to the following calls (compile() and so on) and that
588           specifies an opened WinPcap session. In case of problems, it
589           returns "undef" and the $err variable keeps the error message.
590
591       pcap_setbuff($pcap, $dim)
592           Sets the size of the kernel buffer associated with an adapter.
593           $dim specifies the size of the buffer in bytes.  The return value
594           is 0 when the call succeeds, -1 otherwise.
595
596           If an old buffer was already created with a previous call to
597           setbuff(), it is deleted and its content is discarded.  open_live()
598           creates a 1 MB buffer by default.
599
600       pcap_setmode($pcap, $mode)
601           Sets the working mode of the interface $pcap to $mode.  Valid
602           values for $mode are "MODE_CAPT" (default capture mode) and
603           "MODE_STAT" (statistical mode).
604
605       pcap_setmintocopy($pcap_t, $size)
606           Changes the minimum amount of data in the kernel buffer that causes
607           a read from the application to return (unless the timeout expires).
608
609       pcap_getevent($pcap)
610           Returns the "Win32::Event" object associated with the interface
611           $pcap. Can be used to wait until the driver's buffer contains some
612           data without performing a read. See Win32::Event.
613
614       pcap_sendpacket($pcap, $packet)
615           Send a raw packet to the network. $pcap is the interface that will
616           be used to send the packet, $packet contains the data of the packet
617           to send (including the various protocol headers). The MAC CRC
618           doesn't need to be included, because it is transparently calculated
619           and added by the network interface driver. The return value is 0 if
620           the packet is successfully sent, -1 otherwise.
621
622       pcap_sendqueue_alloc($memsize)
623           This function allocates and returns a send queue, i.e. a buffer
624           containing a set of raw packets that will be transmitted on the
625           network with sendqueue_transmit().
626
627           $memsize is the size, in bytes, of the queue, therefore it
628           determines the maximum amount of data that the queue will contain.
629           This memory is automatically deallocated when the queue ceases to
630           exist.
631
632       pcap_sendqueue_queue($queue, \%header, $packet)
633           Adds a packet at the end of the send queue pointed by $queue. The
634           packet header %header has the same format as that passed to the
635           loop() callback. $ackekt is a buffer with the data of the packet.
636
637           The %headerr header structure is the same used by WinPcap and
638           libpcap to store the packets in a file, therefore sending a capture
639           file is straightforward. "Raw packet" means that the sending
640           application will have to include the protocol headers, since every
641           packet is sent to the network as is. The CRC of the packets needs
642           not to be calculated, because it will be transparently added by the
643           network interface.
644
645       pcap_sendqueue_transmit($pcap, $queue, $sync)
646           This function transmits the content of a queue to the wire. $pcapt
647           is the interface on which the packets will be sent, $queue is to a
648           "send_queue" containing the packets to send, $sync determines if
649           the send operation must be synchronized: if it is non-zero, the
650           packets are sent respecting the timestamps, otherwise they are sent
651           as fast as possible.
652
653           The return value is the amount of bytes actually sent. If it is
654           smaller than the size parameter, an error occurred during the send.
655           The error can be caused by a driver/adapter problem or by an
656           inconsistent/bogus send queue.
657

CONSTANTS

659       "Net::Pcap" exports by default the names of several constants in order
660       to ease the development of programs. See "EXPORTS" for details about
661       which constants are exported.
662
663       Here are the descriptions of a few data link types. See pcap(3) for a
664       more complete description and semantics associated with each data link.
665
666       •   "DLT_NULL" - BSD loopback encapsulation
667
668       •   "DLT_EN10MB" - Ethernet (10Mb, 100Mb, 1000Mb, and up)
669
670       •   "DLT_RAW" - raw IP
671
672       •   "DLT_IEEE802" - IEEE 802.5 Token Ring
673
674       •   "DLT_IEEE802_11" - IEEE 802.11 wireless LAN
675
676       •   "DLT_FRELAY" - Frame Relay
677
678       •   "DLT_FDDI" - FDDI
679
680       •   "DLT_SLIP" - Serial Line IP
681
682       •   "DLT_PPP" - PPP (Point-to-point Protocol)
683
684       •   "DLT_PPP_SERIAL" - PPP over serial with HDLC encapsulation
685
686       •   "DLT_PPP_ETHER" - PPP over Ethernet
687
688       •   "DLT_IP_OVER_FC" - RFC  2625  IP-over-Fibre  Channel
689
690       •   "DLT_AX25" - Amateur Radio AX.25
691
692       •   "DLT_LINUX_IRDA" - Linux-IrDA
693
694       •   "DLT_LTALK" - Apple  LocalTalk
695
696       •   "DLT_APPLE_IP_OVER_IEEE1394" - Apple IP-over-IEEE 1394 (a.k.a.
697           Firewire)
698

DIAGNOSTICS

700       "arg%d not a scalar ref"
701       "arg%d not a hash ref"
702       "arg%d not a reference"
703           (F) These errors occur if you forgot to give a reference to a
704           function which expect one or more of its arguments to be
705           references.
706

BUGS

708       Please report any bugs or feature requests to
709       "bug-Net-Pcap@rt.cpan.org", or through the web interface at
710       <http://rt.cpan.org/Dist/Display.html?Queue=Net-Pcap>.  I will be
711       notified, and then you'll automatically be notified of progress on your
712       bug as I make changes.
713
714       Currently known bugs:
715
716       •   the "ps_recv" field is not correctly set; see t/07-stats.t
717
718       •   pcap_file() seems to always returns "undef" for live connection and
719           causes segmentation fault for dump files; see t/10-fileno.t
720
721       •   pcap_fileno() is documented to return -1 when called on save file,
722           but seems to always return an actual file number.  See
723           t/10-fileno.t
724
725       •   pcap_dump_file() seems to corrupt something somewhere, and makes
726           scripts dump core. See t/05-dump.t
727

EXAMPLES

729       See the eg/ and t/ directories of the "Net::Pcap" distribution for
730       examples on using this module.
731

SEE ALSO

733   Perl Modules
734       the NetPacket or Net::Frame modules to assemble and disassemble
735       packets.
736
737       Net::Pcap::Reassemble for reassembly of TCP/IP fragments.
738
739       POE::Component::Pcap for using "Net::Pcap" within POE-based programs.
740
741       AnyEvent::Pcap for using "Net::Pcap" within AnyEvent-based programs.
742
743       Net::Packet or NetPacket for decoding and creating network packets.
744
745       Net::Pcap::Easy is a module which provides an easier, more Perl-ish API
746       than "Net::Pcap" and integrates some facilities from Net::Netmask and
747       NetPacket.
748
749   Base Libraries
750       pcap(3), tcpdump(8)
751
752       The source code for the pcap(3) library is available from
753       <http://www.tcpdump.org/>
754
755       The source code and binary for the Win32 version of the pcap library,
756       WinPcap, is available from <http://www.winpcap.org/>
757
758   Articles
759       Hacking Linux Exposed: Sniffing with Net::Pcap to stealthily managing
760       iptables rules remotely,
761       <http://www.hackinglinuxexposed.com/articles/20030730.html>
762
763       PerlMonks node about Net::Pcap, <http://perlmonks.org/?node_id=170648>
764

AUTHORS

766       Current maintainer is Sébastien Aperghis-Tramoni (SAPER) with the help
767       of Tim Wilde (TWILDE).
768
769       Complete list of authors & contributors:
770
771       •   Bo Adler (BOADLER) <thumper (at) alumni.caltech.edu>
772
773       •   Craig Davison
774
775       •   David Farrell
776
777       •   David N. Blank-Edelman <dnb (at) ccs.neu.edu>
778
779       •   James Rouzier (ROUZIER)
780
781       •   Jean-Louis Morel (JLMOREL) <jl_morel (at) bribes.org>
782
783       •   Marco Carnut (KCARNUT) <kiko (at) tempest.com.br>
784
785       •   Patrice Auffret (GOMOR)
786
787       •   Peter Lister (PLISTER) <p.lister (at) cranfield.ac.uk>
788
789       •   Rafaël Garcia-Suarez (RGARCIA)
790
791       •   Sébastien Aperghis-Tramoni (SAPER) <sebastien (at) aperghis.net>
792
793       •   Tim Potter (TIMPOTTER) <tpot (at) frungy.org>
794
795       •   Tim Wilde (TWILDE)
796

HISTORY

798       The original version of "Net::Pcap", version 0.01, was written by Peter
799       Lister using SWIG.
800
801       Version 0.02 was created by Bo Adler with a few bugfixes but not
802       uploaded to CPAN. It could be found at:
803       <http://www.buttsoft.com/~thumper/software/perl/Net-Pcap/>
804
805       Versions 0.03 and 0.04 were created by Tim Potter who entirely rewrote
806       "Net::Pcap" using XS and wrote the documentation, with the help of
807       David N. Blank-Edelman for testing and general polishing.
808
809       Version 0.05 was released by Marco Carnut with fixes to make it work
810       with Cygwin and WinPcap.
811
812       Version 0.04.02 was independently created by Jean-Louis Morel but not
813       uploaded on the CPAN. It can be found here:
814       <http://www.bribes.org/perl/wnetpcap.html>
815
816       Based on Tim Potter's version 0.04, it included fixes for WinPcap and
817       added wrappers for several new libpcap functions as well as WinPcap
818       specific functions.
819

ACKNOWLEDGEMENTS

821       To Paul Johnson for his module Devel::Cover and his patience for
822       helping me using it with XS code, which revealed very useful for
823       writing more tests.
824
825       To the beta-testers: Jean-Louis Morel, Max Maischen, Philippe Bruhat,
826       David Morel, Scott Lanning, Rafael Garcia-Suarez, Karl Y. Pradene.
827
829       Copyright (C) 2005-2016 Sébastien Aperghis-Tramoni and contributors.
830       All rights reserved.
831
832       Copyright (C) 2003 Marco Carnut. All rights reserved.
833
834       Copyright (C) 1999, 2000 Tim Potter. All rights reserved.
835
836       Copyright (C) 1998 Bo Adler. All rights reserved.
837
838       Copyright (C) 1997 Peter Lister. All rights reserved.
839
840       This program is free software; you can redistribute it and/or modify it
841       under the same terms as Perl itself.
842
843
844
845perl v5.36.0                      2023-01-23                           Pcap(3)
Impressum