1PCAP(3PCAP)                                                        PCAP(3PCAP)
2
3
4

NAME

6       pcap - Packet Capture library
7

SYNOPSIS

9       #include <pcap/pcap.h>
10

DESCRIPTION

12       The  Packet  Capture  library provides a high level interface to packet
13       capture systems. All packets on the network, even  those  destined  for
14       other  hosts,  are accessible through this mechanism.  It also supports
15       saving captured packets to a ``savefile'', and reading packets  from  a
16       ``savefile''.
17
18   Opening a capture handle for reading
19       To  open  a handle for a live capture, given the name of the network or
20       other interface on which the capture should  be  done,  call  pcap_cre‐
21       ate(),  set the appropriate options on the handle, and then activate it
22       with pcap_activate().
23
24       To obtain a list of devices that can be opened for a live capture, call
25       pcap_findalldevs();  to  free  the list returned by pcap_findalldevs(),
26       call pcap_freealldevs().  pcap_lookupdev() will return the first device
27       on that list that is not a ``loopback`` network interface.
28
29       To  open  a handle for a ``savefile'' from which to read packets, given
30       the pathname of the ``savefile'', call pcap_open_offline(); to set up a
31       handle  for  a ``savefile'', given a FILE * referring to a file already
32       opened for reading, call pcap_fopen_offline().
33
34       In order to get a ``fake'' pcap_t for use in routines  that  require  a
35       pcap_t  as  an  argument,  such  as routines to open a ``savefile'' for
36       writing and to compile a filter expression, call pcap_open_dead().
37
38       pcap_create(),    pcap_open_offline(),    pcap_fopen_offline(),     and
39       pcap_open_dead() return a pointer to a pcap_t, which is the handle used
40       for reading packets from the capture stream or  the  ``savefile'',  and
41       for  finding  out information about the capture stream or ``savefile''.
42       To close a handle, use pcap_close().
43
44       The options that can be set on a capture handle include
45
46       snapshot length
47              If, when capturing, you  capture  the  entire  contents  of  the
48              packet,  that  requires more CPU time to copy the packet to your
49              application, more disk and possibly network bandwidth  to  write
50              the  packet  data  to  a  file,  and more disk space to save the
51              packet.  If you don't need the entire contents of the  packet  -
52              for  example,  if  you are only interested in the TCP headers of
53              packets - you can set the "snapshot length" for the  capture  to
54              an appropriate value.  If the snapshot length is set to snaplen,
55              and snaplen is less than the size of a packet that is  captured,
56              only the first snaplen bytes of that packet will be captured and
57              provided as packet data.
58
59              A snapshot length of 65535 should be sufficient, on most if  not
60              all networks, to capture all the data available from the packet.
61
62              The snapshot length is set with pcap_set_snaplen().
63
64       promiscuous mode
65              On  broadcast  LANs  such  as  Ethernet,  if  the  network isn't
66              switched, or if the adapter is connected to a "mirror port" on a
67              switch to which all packets passing through the switch are sent,
68              a network adapter receives all packets  on  the  LAN,  including
69              unicast  or multicast packets not sent to a network address that
70              the network adapter isn't configured to recognize.
71
72              Normally, the adapter will discard those packets; however,  many
73              network  adapters support "promiscuous mode", which is a mode in
74              which all packets, even if they are not sent to an address  that
75              the  adapter recognizes, are provided to the host.  This is use‐
76              ful for passively capturing traffic between two  or  more  other
77              hosts for analysis.
78
79              Note  that even if an application does not set promiscuous mode,
80              the adapter could well be in promiscuous  mode  for  some  other
81              reason.
82
83              For  now,  this doesn't work on the "any" device; if an argument
84              of "any" or NULL is supplied, the setting of promiscuous mode is
85              ignored.
86
87              Promiscuous mode is set with pcap_set_promisc().
88
89       monitor mode
90              On IEEE 802.11 wireless LANs, even if an adapter is in promiscu‐
91              ous mode, it will supply to the host only frames for the network
92              with  which  it's  associated.   It  might also supply only data
93              frames, not management or control frames, and might not  provide
94              the  802.11  header or radio information pseudo-header for those
95              frames.
96
97              In "monitor mode",  sometimes  also  called  "rfmon  mode"  (for
98              "Radio  Frequency  MONitor"), the adapter will supply all frames
99              that it receives,  with  802.11  headers,  and  might  supply  a
100              pseudo-header with radio information about the frame as well.
101
102              Note  that  in  monitor mode the adapter might disassociate from
103              the network with which it's associated, so that you will not  be
104              able to use any wireless networks with that adapter.  This could
105              prevent accessing files on a network server, or  resolving  host
106              names or network addresses, if you are capturing in monitor mode
107              and are not connected to another network with another adapter.
108
109              Monitor    mode    is    set    with    pcap_set_rfmon(),    and
110              pcap_can_set_rfmon() can be used to determine whether an adapter
111              can be put into monitor mode.
112
113       packet buffer timeout
114              If, when capturing,  packets  are  delivered  as  soon  as  they
115              arrive,  the  application capturing the packets will be woken up
116              for each packet as it arrives, and might have  to  make  one  or
117              more calls to the operating system to fetch each packet.
118
119              If,  instead,  packets are not delivered as soon as they arrive,
120              but are delivered after a short delay (called a  "packet  buffer
121              timeout"),  more  than  one packet can be accumulated before the
122              packets are delivered, so that a single wakeup would be done for
123              multiple  packets,  and  each set of calls made to the operating
124              system would supply  multiple  packets,  rather  than  a  single
125              packet.  This reduces the per-packet CPU overhead if packets are
126              arriving at a high rate, increasing the number  of  packets  per
127              second that can be captured.
128
129              The  packet  buffer  timeout  is required so that an application
130              won't wait for the operating system's capture buffer to fill  up
131              before  packets  are  delivered; if packets are arriving slowly,
132              that wait could take an arbitrarily long period of time.
133
134              Not all platforms support a packet buffer timeout; on  platforms
135              that  don't, the packet buffer timeout is ignored.  A zero value
136              for the timeout, on platforms that support a packet buffer time‐
137              out,  will  cause a read to wait forever to allow enough packets
138              to arrive, with no timeout.  A negative value  is  invalid;  the
139              result  of  setting  the  timeout  to a negative value is unpre‐
140              dictable.
141
142              NOTE: the packet buffer timeout cannot be used  to  cause  calls
143              that  read  packets  to  return within a limited period of time,
144              because, on some platforms, the packet buffer timeout isn't sup‐
145              ported,  and,  on other platforms, the timer doesn't start until
146              at least one packet arrives.  This means that the packet  buffer
147              timeout  should  NOT  be  used,  for  example, in an interactive
148              application to allow the packet capture  loop  to  ``poll''  for
149              user  input  periodically,  as  there's no guarantee that a call
150              reading packets will return after the timeout expires even if no
151              packets have arrived.
152
153              The packet buffer timeout is set with pcap_set_timeout().
154
155       buffer size
156              Packets  that  arrive  for  a capture are stored in a buffer, so
157              that they do not have to be read by the application as  soon  as
158              they arrive.  On some platforms, the buffer's size can be set; a
159              size that's too small could mean that, if too many  packets  are
160              being  captured and the snapshot length doesn't limit the amount
161              of data that's buffered, packets could be dropped if the  buffer
162              fills  up before the application can read packets from it, while
163              a size that's too large could use  more  non-pageable  operating
164              system  memory  than  is necessary to prevent packets from being
165              dropped.
166
167              The buffer size is set with pcap_set_buffer_size().
168
169       timestamp type
170              On some platforms, the time stamp given to packets on live  cap‐
171              tures  can  come  from different sources that can have different
172              resolutions or that can have different relationships to the time
173              values  for  the current time supplied by routines on the native
174              operating system.  See pcap-tstamp(7) for a list of  time  stamp
175              types.
176
177              The time stamp type is set with pcap_set_tstamp_type().
178
179       Reading packets from a network interface may require that you have spe‐
180       cial privileges:
181
182       Under SunOS 3.x or 4.x with NIT or BPF:
183              You must have read access to /dev/nit or /dev/bpf*.
184
185       Under Solaris with DLPI:
186              You must have read/write access to the  network  pseudo  device,
187              e.g.   /dev/le.   On at least some versions of Solaris, however,
188              this is not sufficient to allow tcpdump to capture in  promiscu‐
189              ous mode; on those versions of Solaris, you must be root, or the
190              application capturing packets must be installed setuid to  root,
191              in  order  to  capture  in promiscuous mode.  Note that, on many
192              (perhaps all) interfaces, if you don't  capture  in  promiscuous
193              mode,  you  will  not see any outgoing packets, so a capture not
194              done in promiscuous mode may not be very useful.
195
196              In newer versions of Solaris,  you  must  have  been  given  the
197              net_rawaccess  privilege;  this is both necessary and sufficient
198              to give you access to the network pseudo-device -  there  is  no
199              need  to  change  the  privileges on that device.  A user can be
200              given that privilege by, for example, adding that  privilege  to
201              the user's defaultpriv key with the usermod (8) command.
202
203       Under HP-UX with DLPI:
204              You  must  be  root or the application capturing packets must be
205              installed setuid to root.
206
207       Under IRIX with snoop:
208              You must be root or the application capturing  packets  must  be
209              installed setuid to root.
210
211       Under Linux:
212              You  must  be  root or the application capturing packets must be
213              installed setuid to root (unless your distribution has a  kernel
214              that  supports  capability  bits such as CAP_NET_RAW and code to
215              allow those capability bits to be given to  particular  accounts
216              and  to cause those bits to be set on a user's initial processes
217              when they log in, in which case you  must  have  CAP_NET_RAW  in
218              order  to capture and CAP_NET_ADMIN to enumerate network devices
219              with, for example, the -D flag).
220
221       Under ULTRIX and Digital UNIX/Tru64 UNIX:
222              Any user may capture network traffic.   However,  no  user  (not
223              even  the  super-user)  can  capture  in  promiscuous mode on an
224              interface unless the  super-user  has  enabled  promiscuous-mode
225              operation  on that interface using pfconfig(8), and no user (not
226              even the super-user) can capture unicast traffic received by  or
227              sent  by  the  machine on an interface unless the super-user has
228              enabled copy-all-mode operation on that interface  using  pfcon‐
229              fig,  so useful packet capture on an interface probably requires
230              that either promiscuous-mode or copy-all-mode operation, or both
231              modes of operation, be enabled on that interface.
232
233       Under BSD (this includes macOS):
234              You  must  have  read  access to /dev/bpf* on systems that don't
235              have a cloning BPF device, or to /dev/bpf on  systems  that  do.
236              On  BSDs  with a devfs (this includes macOS), this might involve
237              more than just having somebody with  super-user  access  setting
238              the  ownership  or  permissions  on  the  BPF devices - it might
239              involve configuring devfs to set the  ownership  or  permissions
240              every  time  the  system  is booted, if the system even supports
241              that; if it doesn't support that, you might have  to  find  some
242              other way to make that happen at boot time.
243
244       Reading a saved packet file doesn't require special privileges.
245
246       The  packets  read from the handle may include a ``pseudo-header'' con‐
247       taining various forms of packet  meta-data,  and  probably  includes  a
248       link-layer  header  whose  contents  can  differ  for different network
249       interfaces.  To determine the format of the  packets  supplied  by  the
250       handle,  call  pcap_datalink();  https://www.tcpdump.org/linktypes.html
251       lists the values it returns and describes the packet formats that  cor‐
252       respond to those values.
253
254       Do NOT assume that the packets for a given capture or ``savefile`` will
255       have any given link-layer header type, such as DLT_EN10MB for Ethernet.
256       For  example,  the  "any" device on Linux will have a link-layer header
257       type of DLT_LINUX_SLL even if all devices on the system at the time the
258       "any"  device  is  opened  have  some  other  data  link  type, such as
259       DLT_EN10MB for Ethernet.
260
261       To obtain the FILE * corresponding to a pcap_t  opened  for  a  ``save‐
262       file'', call pcap_file().
263
264       Routines
265
266              pcap_create(3PCAP)
267                     get a pcap_t for live capture
268
269              pcap_activate(3PCAP)
270                     activate a pcap_t for live capture
271
272              pcap_findalldevs(3PCAP)
273                     get  a list of devices that can be opened for a live cap‐
274                     ture
275
276              pcap_freealldevs(3PCAP)
277                     free list of devices
278
279              pcap_lookupdev(3PCAP)
280                     get first non-loopback device on that list
281
282              pcap_open_offline(3PCAP)
283                     open a pcap_t for a ``savefile'', given a pathname
284
285              pcap_open_offline_with_tstamp_precision(3PCAP)
286                     open a pcap_t for a ``savefile'', given a  pathname,  and
287                     specify the precision to provide for packet time stamps
288
289              pcap_fopen_offline(3PCAP)
290                     open a pcap_t for a ``savefile'', given a FILE *
291
292              pcap_fopen_offline_with_tstamp_precision(3PCAP)
293                     open  a  pcap_t  for  a ``savefile'', given a FILE *, and
294                     specify the precision to provide for packet time stamps
295
296              pcap_open_dead(3PCAP)
297                     create a ``fake'' pcap_t
298
299              pcap_close(3PCAP)
300                     close a pcap_t
301
302              pcap_set_snaplen(3PCAP)
303                     set the snapshot length for  a  not-yet-activated  pcap_t
304                     for live capture
305
306              pcap_snapshot(3PCAP)
307                     get the snapshot length for a pcap_t
308
309              pcap_set_promisc(3PCAP)
310                     set  promiscuous  mode for a not-yet-activated pcap_t for
311                     live capture
312
313              pcap_set_protocol_linux(3PCAP)
314                     set capture protocol for a not-yet-activated  pcap_t  for
315                     live capture (Linux only)
316
317              pcap_set_rfmon(3PCAP)
318                     set  monitor mode for a not-yet-activated pcap_t for live
319                     capture
320
321              pcap_can_set_rfmon(3PCAP)
322                     determine whether monitor mode can be set  for  a  pcap_t
323                     for live capture
324
325              pcap_set_timeout(3PCAP)
326                     set  packet buffer timeout for a not-yet-activated pcap_t
327                     for live capture
328
329              pcap_set_buffer_size(3PCAP)
330                     set buffer size for a not-yet-activated pcap_t  for  live
331                     capture
332
333              pcap_set_tstamp_type(3PCAP)
334                     set  time  stamp  type for a not-yet-activated pcap_t for
335                     live capture
336
337              pcap_list_tstamp_types(3PCAP)
338                     get list of available time stamp  types  for  a  not-yet-
339                     activated pcap_t for live capture
340
341              pcap_free_tstamp_types(3PCAP)
342                     free list of available time stamp types
343
344              pcap_tstamp_type_val_to_name(3PCAP)
345                     get name for a time stamp type
346
347              pcap_tstamp_type_val_to_description(3PCAP)
348                     get description for a time stamp type
349
350              pcap_tstamp_type_name_to_val(3PCAP)
351                     get time stamp type corresponding to a name
352
353              pcap_set_tstamp_precision(3PCAP)
354                     set  time  stamp precision for a not-yet-activated pcap_t
355                     for live capture
356
357              pcap_get_tstamp_precision(3PCAP)
358                     get the time stamp precision of a pcap_t for live capture
359
360              pcap_datalink(3PCAP)
361                     get link-layer header type for a pcap_t
362
363              pcap_file(3PCAP)
364                     get the FILE * for a pcap_t opened for a ``savefile''
365
366              pcap_is_swapped(3PCAP)
367                     determine whether a ``savefile'' being read came  from  a
368                     machine with the opposite byte order
369
370              pcap_major_version(3PCAP)
371              pcap_minor_version(3PCAP)
372                     get  the  major and minor version of the file format ver‐
373                     sion for a ``savefile''
374
375   Selecting a link-layer header type for a live capture
376       Some devices may provide more than  one  link-layer  header  type.   To
377       obtain a list of all link-layer header types provided by a device, call
378       pcap_list_datalinks() on an activated pcap_t for the device.  To free a
379       list  of  link-layer  header types, call pcap_free_datalinks().  To set
380       the link-layer header type  for  a  device,  call  pcap_set_datalink().
381       This  should be done after the device has been activated but before any
382       packets are read and before any filters are compiled or installed.
383
384       Routines
385
386              pcap_list_datalinks(3PCAP)
387                     get a list of link-layer header types for a device
388
389              pcap_free_datalinks(3PCAP)
390                     free list of link-layer header types
391
392              pcap_set_datalink(3PCAP)
393                     set link-layer header type for a device
394
395              pcap_datalink_val_to_name(3PCAP)
396                     get name for a link-layer header type
397
398              pcap_datalink_val_to_description(3PCAP)
399                     get description for a link-layer header type
400
401              pcap_datalink_name_to_val(3PCAP)
402                     get link-layer header type corresponding to a name
403
404   Reading packets
405       Packets are read with pcap_dispatch() or pcap_loop(), which process one
406       or  more  packets,  calling a callback routine for each packet, or with
407       pcap_next() or pcap_next_ex(), which return the next packet.  The call‐
408       back  for  pcap_dispatch()  and  pcap_loop() is supplied a pointer to a
409       struct pcap_pkthdr, which includes the following members:
410
411              ts     a struct timeval containing the time when the packet  was
412                     captured
413
414              caplen a  bpf_u_int32  giving  the number of bytes of the packet
415                     that are available from the capture
416
417              len    a bpf_u_int32 giving the length of the packet,  in  bytes
418                     (which  might  be more than the number of bytes available
419                     from the capture, if the length of the packet  is  larger
420                     than the maximum number of bytes to capture).
421
422       The  callback  is  also  supplied  a  const u_char pointer to the first
423       caplen (as given in the struct pcap_pkthdr mentioned  above)  bytes  of
424       data  from the packet.  This won't necessarily be the entire packet; to
425       capture the entire packet, you will have to provide a value for snaplen
426       in  your  call  to pcap_set_snaplen() that is sufficiently large to get
427       all of the packet's data - a value of 65535  should  be  sufficient  on
428       most if not all networks).  When reading from a ``savefile'', the snap‐
429       shot length specified when the capture was  performed  will  limit  the
430       amount of packet data available.
431
432       pcap_next()  is  passed an argument that points to a struct pcap_pkthdr
433       structure, and fills it in with the time stamp and  length  values  for
434       the packet.  It returns a const u_char to the first caplen bytes of the
435       packet on success, and NULL on error.
436
437       pcap_next_ex() is passed two pointer arguments, one of which points  to
438       a  structpcap_pkthdr*  and  one of which points to a const u_char*.  It
439       sets the first pointer to point to a struct pcap_pkthdr structure  with
440       the  time  stamp  and length values for the packet, and sets the second
441       pointer to point to the first caplen bytes of the packet.
442
443       To force the loop in pcap_dispatch() or pcap_loop() to terminate,  call
444       pcap_breakloop().
445
446       By  default,  when  reading packets from an interface opened for a live
447       capture, pcap_dispatch(), pcap_next(), and pcap_next_ex() will,  if  no
448       packets  are  currently available to be read, block waiting for packets
449       to become available.  On some, but not all, platforms, if a packet buf‐
450       fer  timeout  was  specified,  the wait will terminate after the packet
451       buffer timeout expires; applications should be prepared for this, as it
452       happens  on  some  platforms, but should not rely on it, as it does not
453       happen on other platforms.  Note that the wait  might,  or  might  not,
454       terminate even if no packets are available; applications should be pre‐
455       pared for this to happen, but must not rely on it happening.
456
457       A handle can be put into ``non-blocking mode'', so that those  routines
458       will,  rather  than  blocking, return an indication that no packets are
459       available to read.  Call pcap_setnonblock() to put a handle  into  non-
460       blocking mode or to take it out of non-blocking mode; call pcap_getnon‐
461       block() to determine whether a handle is in  non-blocking  mode.   Note
462       that non-blocking mode does not work correctly in Mac OS X 10.6.
463
464       Non-blocking  mode is often combined with routines such as select(2) or
465       poll(2) or other routines a platform offers to wait for any of a set of
466       descriptors to be ready to read.  To obtain, for a handle, a descriptor
467       that can be used in those routines, call pcap_get_selectable_fd().  Not
468       all  handles have such a descriptor available; pcap_get_selectable_fd()
469       will return -1 if no such descriptor exists.  In addition, for  various
470       reasons,  one or more of those routines will not work properly with the
471       descriptor;  the  documentation  for   pcap_get_selectable_fd()   gives
472       details.   Note  that, just as an attempt to read packets from a pcap_t
473       may not return any packets if the  packet  buffer  timeout  expires,  a
474       select(),  poll(), or other such call may, if the packet buffer timeout
475       expires, indicate that a descriptor is ready to read even if there  are
476       no packets available to read.
477
478       Routines
479
480              pcap_dispatch(3PCAP)
481                     read a bufferful of packets from a pcap_t open for a live
482                     capture or the full set of packets from a pcap_t open for
483                     a ``savefile''
484
485              pcap_loop(3PCAP)
486                     read  packets  from  a pcap_t until an interrupt or error
487                     occurs
488
489              pcap_next(3PCAP)
490                     read the next packet from a pcap_t without an  indication
491                     whether an error occurred
492
493              pcap_next_ex(3PCAP)
494                     read  the next packet from a pcap_t with an error indica‐
495                     tion on an error
496
497              pcap_breakloop(3PCAP)
498                     prematurely terminate  the  loop  in  pcap_dispatch()  or
499                     pcap_loop()
500
501              pcap_setnonblock(3PCAP)
502                     set or clear non-blocking mode on a pcap_t
503
504              pcap_getnonblock(3PCAP)
505                     get the state of non-blocking mode for a pcap_t
506
507              pcap_get_selectable_fd(3PCAP)
508                     attempt to get a descriptor for a pcap_t that can be used
509                     in calls such as select(2) and poll(2)
510
511   Filters
512       In order to cause only certain packets  to  be  returned  when  reading
513       packets, a filter can be set on a handle.  For a live capture, the fil‐
514       tering will be performed in kernel mode, if possible, to avoid  copying
515       ``uninteresting'' packets from the kernel to user mode.
516
517       A filter can be specified as a text string; the syntax and semantics of
518       the string are as described by pcap-filter(7).  A filter string is com‐
519       piled into a program in a pseudo-machine-language by pcap_compile() and
520       the resulting program can be made a filter for a handle with  pcap_set‐
521       filter().   The  result  of  pcap_compile() can be freed with a call to
522       pcap_freecode().  pcap_compile() may require a network mask for certain
523       expressions  in the filter string; pcap_lookupnet() can be used to find
524       the network address and network mask for a given capture device.
525
526       A compiled filter can also be applied directly to  a  packet  that  has
527       been read using pcap_offline_filter().
528
529       Routines
530
531              pcap_compile(3PCAP)
532                     compile  filter  expression  to a pseudo-machine-language
533                     code program
534
535              pcap_freecode(3PCAP)
536                     free a filter program
537
538              pcap_setfilter(3PCAP)
539                     set filter for a pcap_t
540
541              pcap_lookupnet(3PCAP)
542                     get network address and network mask for a capture device
543
544              pcap_offline_filter(3PCAP)
545                     apply a filter program to a packet
546
547   Incoming and outgoing packets
548       By default, libpcap will attempt to capture both packets  sent  by  the
549       machine  and packets received by the machine.  To limit it to capturing
550       only packets received by the machine or, if possible, only packets sent
551       by the machine, call pcap_setdirection().
552
553       Routines
554
555              pcap_setdirection(3PCAP)
556                     specify  whether  to  capture  incoming packets, outgoing
557                     packets, or both
558
559   Capture statistics
560       To get statistics about packets received and dropped in a live capture,
561       call pcap_stats().
562
563       Routines
564
565              pcap_stats(3PCAP)
566                     get capture statistics
567
568   Opening a handle for writing captured packets
569       To  open  a  ``savefile`` to which to write packets, given the pathname
570       the ``savefile'' should have, call pcap_dump_open().  To open a ``save‐
571       file``  to  which to write packets, given the pathname the ``savefile''
572       should have, call pcap_dump_open(); to set up a handle  for  a  ``save‐
573       file'',  given a FILE * referring to a file already opened for writing,
574       call pcap_dump_fopen().  They each return pointers to a  pcap_dumper_t,
575       which  is  the handle used for writing packets to the ``savefile''.  If
576       it succeeds, it will have created the file  if  it  doesn't  exist  and
577       truncated  the  file  if it does exist.  To close a pcap_dumper_t, call
578       pcap_dump_close().
579
580       Routines
581
582              pcap_dump_open(3PCAP)
583                     open a pcap_dumper_t for a ``savefile``, given a pathname
584
585              pcap_dump_fopen(3PCAP)
586                     open a pcap_dumper_t for a ``savefile``, given a FILE *
587
588              pcap_dump_close(3PCAP)
589                     close a pcap_dumper_t
590
591              pcap_dump_file(3PCAP)
592                     get the FILE * for a pcap_dumper_t opened for  a  ``save‐
593                     file''
594
595   Writing packets
596       To  write a packet to a pcap_dumper_t, call pcap_dump().  Packets writ‐
597       ten with pcap_dump() may be buffered,  rather  than  being  immediately
598       written  to the ``savefile''.  Closing the pcap_dumper_t will cause all
599       buffered-but-not-yet-written packets to be written to the ``savefile''.
600       To  force all packets written to the pcap_dumper_t, and not yet written
601       to the ``savefile'' because they're buffered by the  pcap_dumper_t,  to
602       be written to the ``savefile'', without closing the pcap_dumper_t, call
603       pcap_dump_flush().
604
605       Routines
606
607              pcap_dump(3PCAP)
608                     write packet to a pcap_dumper_t
609
610              pcap_dump_flush(3PCAP)
611                     flush buffered packets written to a pcap_dumper_t to  the
612                     ``savefile''
613
614              pcap_dump_ftell(3PCAP)
615                     get current file position for a pcap_dumper_t
616
617   Injecting packets
618       If you have the required privileges, you can inject packets onto a net‐
619       work  with  a  pcap_t  for  a  live  capture,  using  pcap_inject()  or
620       pcap_sendpacket().  (The two routines exist for compatibility with both
621       OpenBSD and WinPcap; they perform the same function, but have different
622       return values.)
623
624       Routines
625
626              pcap_inject(3PCAP)
627              pcap_sendpacket(3PCAP)
628                     transmit a packet
629
630   Reporting errors
631       Some  routines return error or warning status codes; to convert them to
632       a string, use pcap_statustostr().
633
634       Routines
635
636              pcap_statustostr(3PCAP)
637                     get a string for an error or warning status code
638
639   Getting library version information
640       To  get  a  string  giving  version  information  about  libpcap,  call
641       pcap_lib_version().
642
643       Routines
644
645              pcap_lib_version(3PCAP)
646                     get library version string
647

BACKWARDS COMPATIBILITY

649       In  versions of libpcap prior to 1.0, the pcap.h header file was not in
650       a pcap directory on most platforms; if you are writing  an  application
651       that  must  work on versions of libpcap prior to 1.0, include <pcap.h>,
652       which  will  include  <pcap/pcap.h>  for  you,  rather  than  including
653       <pcap/pcap.h>.
654
655       pcap_create()  and  pcap_activate()  were  not available in versions of
656       libpcap prior to 1.0; if you are writing an application that must  work
657       on versions of libpcap prior to 1.0, either use pcap_open_live() to get
658       a handle for a live capture or, if you want to be able to use the addi‐
659       tional capabilities offered by using pcap_create() and pcap_activate(),
660       use an autoconf(1) script or some other configuration script  to  check
661       whether  the  libpcap  1.0 APIs are available and use them only if they
662       are.
663

SEE ALSO

665       autoconf(1),  tcpdump(8),  tcpslice(8),  pcap-filter(7),   pfconfig(8),
666       usermod(8)
667

AUTHORS

669       The original authors of libpcap are:
670
671       Van  Jacobson,  Craig  Leres  and  Steven  McCanne, all of the Lawrence
672       Berkeley National Laboratory, University of California, Berkeley, CA.
673
674       The current version is available from "The Tcpdump Group"'s Web site at
675
676              https://www.tcpdump.org/
677

BUGS

679       To report a security issue  please  send  an  e-mail  to  security@tcp‐
680       dump.org.
681
682       To  report  bugs and other problems, contribute patches, request a fea‐
683       ture, provide generic feedback etc please see the file CONTRIBUTING  in
684       the libpcap source tree root.
685
686
687
688                                 20 April 2018                     PCAP(3PCAP)
Impressum