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.20
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()",
131           "fileno()".  Using these short names is now discouraged, and may be
132           removed in 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
151           filled 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
160           filled 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()"
351           will 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
480           possible to read packets without blocking, if such a descriptor
481           exists, or -1, if no such descriptor exists. Some network devices
482           opened with "pcap_open_live()" do not support "select()" or
483           "poll()", so -1 is returned for those devices.  See pcap(3) for
484           more details.
485
486   Error handling
487       pcap_geterr($pcap)
488           Returns an error message for the last error associated with the
489           packet capture device $pcap.
490
491       pcap_strerror($errno)
492           Returns a string describing error number $errno.
493
494       pcap_perror($pcap, $prefix)
495           Prints the text of the last error associated with descriptor $pcap
496           on standard error, prefixed by $prefix.
497
498   Information
499       pcap_lib_version()
500           Returns the name and version of the "pcap" library the module was
501           linked against.
502
503   Perl specific functions
504       The following functions are specific to the Perl binding of libpcap.
505
506       pcap_perl_settings($setting)
507           Modify internal behaviour of the Perl interpreter.
508
509           •   "PERL_SIGNALS_SAFE", "PERL_SIGNALS_UNSAFE" respectively enable
510               safe or unsafe signals delivery. Returns the previous value of
511               "PL_signals".  See "Signals handling".
512
513               Example:
514
515                   local $SIG{ALRM} = sub { pcap_breakloop() };
516                   alarm 60;
517
518                   pcap_perl_settings(PERL_SIGNALS_UNSAFE);
519                   pcap_loop($pcap, 10, \&process_packet, "");
520                   pcap_perl_settings(PERL_SIGNALS_SAFE);
521
522   WinPcap specific functions
523       The following functions are only available with WinPcap, the Win32 port
524       of the Pcap library.  If a called function is not available, it will
525       cleanly "croak()".
526
527       pcap_createsrcstr(\$source, $type, $host, $port, $name, \$err)
528           Accepts a set of strings (host name, port, ...), and stores the
529           complete source string according to the new format (e.g.
530           "rpcap://1.2.3.4/eth0") in $source.
531
532           This function is provided in order to help the user creating the
533           source string according to the new format. An unique source string
534           is used in order to make easy for old applications to use the
535           remote facilities.  Think about tcpdump(1), for example, which has
536           only one way to specify the interface on which the capture has to
537           be started. However, GUI-based programs can find more useful to
538           specify hostname, port and interface name separately. In that case,
539           they can use this function to create the source string before
540           passing it to the "pcap_open()" function.
541
542           Returns 0 if everything is fine, -1 if some errors occurred. The
543           string containing the complete source is returned in the $source
544           variable.
545
546       pcap_parsesrcstr($source, \$type, \$host, \$port, \$name, \$err)
547           Parse the source string and stores the pieces in which the source
548           can be split in the corresponding variables.
549
550           This call is the other way round of "pcap_createsrcstr()". It
551           accepts a null-terminated string and it returns the parameters
552           related to the source.  This includes:
553
554           •   the type of the source (file, WinPcap on a remote adapter,
555               WinPcap on local adapter), which is determined by the source
556               prefix ("PCAP_SRC_IF_STRING" and so on);
557
558           •   the host on which the capture has to be started (only for
559               remote captures);
560
561           •   the raw name of the source (file name, name of the remote
562               adapter, name of the local adapter), without the source prefix.
563               The string returned does not include the type of the source
564               itself (i.e. the string returned does not include "file://" or
565               "rpcap://" or such).
566
567           The user can omit some parameters in case it is not interested in
568           them.
569
570           Returns 0 if everything is fine, -1 if some errors occurred. The
571           requested values (host name, network port, type of the source) are
572           returned into the proper variables passed by reference.
573
574       pcap_open($source, $snaplen, $flags, $read_timeout, \$auth, \$err)
575           Open a generic source in order to capture / send (WinPcap only)
576           traffic.
577
578           The "pcap_open()" replaces all the "pcap_open_xxx()" functions with
579           a single call.
580
581           This function hides the differences between the different
582           "pcap_open_xxx()" functions so that the programmer does not have to
583           manage different opening function. In this way, the true "open()"
584           function is decided according to the source type, which is included
585           into the source string (in the form of source prefix).
586
587           Returns a pointer to a pcap descriptor which can be used as a
588           parameter to the following calls ("compile()" and so on) and that
589           specifies an opened WinPcap session. In case of problems, it
590           returns "undef" and the $err variable keeps the error message.
591
592       pcap_setbuff($pcap, $dim)
593           Sets the size of the kernel buffer associated with an adapter.
594           $dim specifies the size of the buffer in bytes.  The return value
595           is 0 when the call succeeds, -1 otherwise.
596
597           If an old buffer was already created with a previous call to
598           "setbuff()", it is deleted and its content is discarded.
599           "open_live()" creates a 1 MB buffer by default.
600
601       pcap_setmode($pcap, $mode)
602           Sets the working mode of the interface $pcap to $mode.  Valid
603           values for $mode are "MODE_CAPT" (default capture mode) and
604           "MODE_STAT" (statistical mode).
605
606       pcap_setmintocopy($pcap_t, $size)
607           Changes the minimum amount of data in the kernel buffer that causes
608           a read from the application to return (unless the timeout expires).
609
610       pcap_getevent($pcap)
611           Returns the "Win32::Event" object associated with the interface
612           $pcap. Can be used to wait until the driver's buffer contains some
613           data without performing a read. See Win32::Event.
614
615       pcap_sendpacket($pcap, $packet)
616           Send a raw packet to the network. $pcap is the interface that will
617           be used to send the packet, $packet contains the data of the packet
618           to send (including the various protocol headers). The MAC CRC
619           doesn't need to be included, because it is transparently calculated
620           and added by the network interface driver. The return value is 0 if
621           the packet is successfully sent, -1 otherwise.
622
623       pcap_sendqueue_alloc($memsize)
624           This function allocates and returns a send queue, i.e. a buffer
625           containing a set of raw packets that will be transmitted on the
626           network with "sendqueue_transmit()".
627
628           $memsize is the size, in bytes, of the queue, therefore it
629           determines the maximum amount of data that the queue will contain.
630           This memory is automatically deallocated when the queue ceases to
631           exist.
632
633       pcap_sendqueue_queue($queue, \%header, $packet)
634           Adds a packet at the end of the send queue pointed by $queue. The
635           packet header %header has the same format as that passed to the
636           "loop()" callback. $ackekt is a buffer with the data of the packet.
637
638           The %headerr header structure is the same used by WinPcap and
639           libpcap to store the packets in a file, therefore sending a capture
640           file is straightforward. "Raw packet" means that the sending
641           application will have to include the protocol headers, since every
642           packet is sent to the network as is. The CRC of the packets needs
643           not to be calculated, because it will be transparently added by the
644           network interface.
645
646       pcap_sendqueue_transmit($pcap, $queue, $sync)
647           This function transmits the content of a queue to the wire. $pcapt
648           is the interface on which the packets will be sent, $queue is to a
649           "send_queue" containing the packets to send, $sync determines if
650           the send operation must be synchronized: if it is non-zero, the
651           packets are sent respecting the timestamps, otherwise they are sent
652           as fast as possible.
653
654           The return value is the amount of bytes actually sent. If it is
655           smaller than the size parameter, an error occurred during the send.
656           The error can be caused by a driver/adapter problem or by an
657           inconsistent/bogus send queue.
658

CONSTANTS

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

DIAGNOSTICS

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

BUGS

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

EXAMPLES

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

SEE ALSO

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

AUTHORS

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

HISTORY

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

ACKNOWLEDGEMENTS

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