1PCAP(3PCAP) PCAP(3PCAP)
2
6 pcap - Packet Capture library
7
9 #include <pcap/pcap.h>
10
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 Initializing
19 pcap_init() initializes the library. It takes an argument giving
20 options; currently, the options are:
21 PCAP_CHAR_ENC_LOCAL
23 Treat all strings supplied as arguments, and return all strings
24 to the caller, as being in the local character encoding.
25 PCAP_CHAR_ENC_UTF_8
27 Treat all strings supplied as arguments, and return all strings
28 to the caller, as being in UTF-8.
29 On UNIX-like systems, the local character encoding is assumed to be
31 UTF-8, so no character encoding transformations are done.
32 On Windows, the local character encoding is the local ANSI code page.
34 If pcap_init() is called, the deprecated pcap_lookupdev() routine
36 always fails, so it should not be used, and, on Windows, pcap_create()
37 does not attempt to handle UTF-16LE strings.
38 If pcap_init() is not called, strings are treated as being in the local
40 ANSI code page on Windows, pcap_lookupdev() will succeed if there is a
41 device on which to capture, and pcap_create() makes an attempt to check
42 whether the string passed as an argument is a UTF-16LE string - note
43 that this attempt is unsafe, as it may run past the end of the string -
44 to handle pcap_lookupdev() returning a UTF-16LE string. Programs that
45 don't call pcap_init() should, on Windows, call pcap_wsockinit() to
46 initialize Winsock; this is not necessary if pcap_init() is called, as
47 pcap_init() will initialize Winsock itself on Windows.
48 Routines
50 pcap_init(3PCAP)
52 initialize the library
53 Opening a capture handle for reading
55 To open a handle for a live capture, given the name of the network or
56 other interface on which the capture should be done, call pcap_cre‐
57 ate(), set the appropriate options on the handle, and then activate it
58 with pcap_activate(). If pcap_activate() fails, the handle should be
59 closed with pcap_close().
60 To obtain a list of devices that can be opened for a live capture, call
62 pcap_findalldevs(); to free the list returned by pcap_findalldevs(),
63 call pcap_freealldevs(). pcap_lookupdev() will return the first device
64 on that list that is not a ``loopback`` network interface.
65 To open a handle for a ``savefile'' from which to read packets, given
67 the pathname of the ``savefile'', call pcap_open_offline(); to set up a
68 handle for a ``savefile'', given a FILE * referring to a file already
69 opened for reading, call pcap_fopen_offline().
70 In order to get a ``fake'' pcap_t for use in routines that require a
72 pcap_t as an argument, such as routines to open a ``savefile'' for
73 writing and to compile a filter expression, call pcap_open_dead().
74 pcap_create(), pcap_open_offline(), pcap_fopen_offline(), and
76 pcap_open_dead() return a pointer to a pcap_t, which is the handle used
77 for reading packets from the capture stream or the ``savefile'', and
78 for finding out information about the capture stream or ``savefile''.
79 To close a handle, use pcap_close().
80 The options that can be set on a capture handle include
82 snapshot length
84 If, when capturing, you capture the entire contents of the
85 packet, that requires more CPU time to copy the packet to your
86 application, more disk and possibly network bandwidth to write
87 the packet data to a file, and more disk space to save the
88 packet. If you don't need the entire contents of the packet -
89 for example, if you are only interested in the TCP headers of
90 packets - you can set the "snapshot length" for the capture to
91 an appropriate value. If the snapshot length is set to snaplen,
92 and snaplen is less than the size of a packet that is captured,
93 only the first snaplen bytes of that packet will be captured and
94 provided as packet data.
95 A snapshot length of 65535 should be sufficient, on most if not
97 all networks, to capture all the data available from the packet.
98 The snapshot length is set with pcap_set_snaplen().
100 promiscuous mode
102 On broadcast LANs such as Ethernet, if the network isn't
103 switched, or if the adapter is connected to a "mirror port" on a
104 switch to which all packets passing through the switch are sent,
105 a network adapter receives all packets on the LAN, including
106 unicast or multicast packets not sent to a network address that
107 the network adapter isn't configured to recognize.
108 Normally, the adapter will discard those packets; however, many
110 network adapters support "promiscuous mode", which is a mode in
111 which all packets, even if they are not sent to an address that
112 the adapter recognizes, are provided to the host. This is use‐
113 ful for passively capturing traffic between two or more other
114 hosts for analysis.
115 Note that even if an application does not set promiscuous mode,
117 the adapter could well be in promiscuous mode for some other
118 reason.
119 For now, this doesn't work on the "any" device; if an argument
121 of "any" or NULL is supplied, the setting of promiscuous mode is
122 ignored.
123 Promiscuous mode is set with pcap_set_promisc().
125 monitor mode
127 On IEEE 802.11 wireless LANs, even if an adapter is in promiscu‐
128 ous mode, it will supply to the host only frames for the network
129 with which it's associated. It might also supply only data
130 frames, not management or control frames, and might not provide
131 the 802.11 header or radio information pseudo-header for those
132 frames.
133 In "monitor mode", sometimes also called "rfmon mode" (for
135 "Radio Frequency MONitor"), the adapter will supply all frames
136 that it receives, with 802.11 headers, and might supply a
137 pseudo-header with radio information about the frame as well.
138 Note that in monitor mode the adapter might disassociate from
140 the network with which it's associated, so that you will not be
141 able to use any wireless networks with that adapter. This could
142 prevent accessing files on a network server, or resolving host
143 names or network addresses, if you are capturing in monitor mode
144 and are not connected to another network with another adapter.
145 Monitor mode is set with pcap_set_rfmon(), and
147 pcap_can_set_rfmon() can be used to determine whether an adapter
148 can be put into monitor mode.
149 packet buffer timeout
151 If, when capturing, packets are delivered as soon as they
152 arrive, the application capturing the packets will be woken up
153 for each packet as it arrives, and might have to make one or
154 more calls to the operating system to fetch each packet.
155 If, instead, packets are not delivered as soon as they arrive,
157 but are delivered after a short delay (called a "packet buffer
158 timeout"), more than one packet can be accumulated before the
159 packets are delivered, so that a single wakeup would be done for
160 multiple packets, and each set of calls made to the operating
161 system would supply multiple packets, rather than a single
162 packet. This reduces the per-packet CPU overhead if packets are
163 arriving at a high rate, increasing the number of packets per
164 second that can be captured.
165 The packet buffer timeout is required so that an application
167 won't wait for the operating system's capture buffer to fill up
168 before packets are delivered; if packets are arriving slowly,
169 that wait could take an arbitrarily long period of time.
170 Not all platforms support a packet buffer timeout; on platforms
172 that don't, the packet buffer timeout is ignored. A zero value
173 for the timeout, on platforms that support a packet buffer time‐
174 out, will cause a read to wait forever to allow enough packets
175 to arrive, with no timeout. A negative value is invalid; the
176 result of setting the timeout to a negative value is unpre‐
177 dictable.
178 NOTE: the packet buffer timeout cannot be used to cause calls
180 that read packets to return within a limited period of time,
181 because, on some platforms, the packet buffer timeout isn't sup‐
182 ported, and, on other platforms, the timer doesn't start until
183 at least one packet arrives. This means that the packet buffer
184 timeout should NOT be used, for example, in an interactive
185 application to allow the packet capture loop to ``poll'' for
186 user input periodically, as there's no guarantee that a call
187 reading packets will return after the timeout expires even if no
188 packets have arrived.
189 The packet buffer timeout is set with pcap_set_timeout().
191 immediate mode
193 In immediate mode, packets are always delivered as soon as they
194 arrive, with no buffering. Immediate mode is set with
195 pcap_set_immediate_mode().
196 buffer size
198 Packets that arrive for a capture are stored in a buffer, so
199 that they do not have to be read by the application as soon as
200 they arrive. On some platforms, the buffer's size can be set; a
201 size that's too small could mean that, if too many packets are
202 being captured and the snapshot length doesn't limit the amount
203 of data that's buffered, packets could be dropped if the buffer
204 fills up before the application can read packets from it, while
205 a size that's too large could use more non-pageable operating
206 system memory than is necessary to prevent packets from being
207 dropped.
208 The buffer size is set with pcap_set_buffer_size().
210 timestamp type
212 On some platforms, the time stamp given to packets on live cap‐
213 tures can come from different sources that can have different
214 resolutions or that can have different relationships to the time
215 values for the current time supplied by routines on the native
216 operating system. See pcap-tstamp(7) for a list of time stamp
217 types.
218 The time stamp type is set with pcap_set_tstamp_type().
220 Reading packets from a network interface may require that you have spe‐
222 cial privileges:
223 Under SunOS 3.x or 4.x with NIT or BPF:
225 You must have read access to /dev/nit or /dev/bpf*.
226 Under Solaris with DLPI:
228 You must have read/write access to the network pseudo device,
229 e.g. /dev/le. On at least some versions of Solaris, however,
230 this is not sufficient to allow tcpdump to capture in promiscu‐
231 ous mode; on those versions of Solaris, you must be root, or the
232 application capturing packets must be installed setuid to root,
233 in order to capture in promiscuous mode. Note that, on many
234 (perhaps all) interfaces, if you don't capture in promiscuous
235 mode, you will not see any outgoing packets, so a capture not
236 done in promiscuous mode may not be very useful.
237 In newer versions of Solaris, you must have been given the
239 net_rawaccess privilege; this is both necessary and sufficient
240 to give you access to the network pseudo-device - there is no
241 need to change the privileges on that device. A user can be
242 given that privilege by, for example, adding that privilege to
243 the user's defaultpriv key with the usermod(8) command.
244 Under HP-UX with DLPI:
246 You must be root or the application capturing packets must be
247 installed setuid to root.
248 Under IRIX with snoop:
250 You must be root or the application capturing packets must be
251 installed setuid to root.
252 Under Linux:
254 You must be root or the application capturing packets must be
255 installed setuid to root, unless your distribution has a kernel
256 that supports capability bits such as CAP_NET_RAW and code to
257 allow those capability bits to be given to particular accounts
258 and to cause those bits to be set on a user's initial processes
259 when they log in, in which case you must have CAP_NET_RAW in
260 order to capture.
261 Under ULTRIX and Digital UNIX/Tru64 UNIX:
263 Any user may capture network traffic. However, no user (not
264 even the super-user) can capture in promiscuous mode on an
265 interface unless the super-user has enabled promiscuous-mode
266 operation on that interface using pfconfig(8), and no user (not
267 even the super-user) can capture unicast traffic received by or
268 sent by the machine on an interface unless the super-user has
269 enabled copy-all-mode operation on that interface using pfcon‐
270 fig, so useful packet capture on an interface probably requires
271 that either promiscuous-mode or copy-all-mode operation, or both
272 modes of operation, be enabled on that interface.
273 Under BSD (this includes macOS):
275 You must have read access to /dev/bpf* on systems that don't
276 have a cloning BPF device, or to /dev/bpf on systems that do.
277 On BSDs with a devfs (this includes macOS), this might involve
278 more than just having somebody with super-user access setting
279 the ownership or permissions on the BPF devices - it might
280 involve configuring devfs to set the ownership or permissions
281 every time the system is booted, if the system even supports
282 that; if it doesn't support that, you might have to find some
283 other way to make that happen at boot time.
284 Reading a saved packet file doesn't require special privileges.
286 The packets read from the handle may include a ``pseudo-header'' con‐
288 taining various forms of packet meta-data, and probably includes a
289 link-layer header whose contents can differ for different network
290 interfaces. To determine the format of the packets supplied by the
291 handle, call pcap_datalink(); https://www.tcpdump.org/linktypes.html
292 lists the values it returns and describes the packet formats that cor‐
293 respond to those values.
294 Do NOT assume that the packets for a given capture or ``savefile`` will
296 have any given link-layer header type, such as DLT_EN10MB for Ethernet.
297 For example, the "any" device on Linux will have a link-layer header
298 type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the sys‐
299 tem at the time the "any" device is opened have some other data link
300 type, such as DLT_EN10MB for Ethernet.
301 To obtain the FILE * corresponding to a pcap_t opened for a ``save‐
303 file'', call pcap_file().
304 Routines
306 pcap_create(3PCAP)
308 get a pcap_t for live capture
309 pcap_activate(3PCAP)
311 activate a pcap_t for live capture
312 pcap_findalldevs(3PCAP)
314 get a list of devices that can be opened for a live cap‐
315 ture
316 pcap_freealldevs(3PCAP)
318 free list of devices
319 pcap_lookupdev(3PCAP)
321 get first non-loopback device on that list
322 pcap_open_offline(3PCAP)
324 open a pcap_t for a ``savefile'', given a pathname
325 pcap_open_offline_with_tstamp_precision(3PCAP)
327 open a pcap_t for a ``savefile'', given a pathname, and
328 specify the precision to provide for packet time stamps
329 pcap_fopen_offline(3PCAP)
331 open a pcap_t for a ``savefile'', given a FILE *
332 pcap_fopen_offline_with_tstamp_precision(3PCAP)
334 open a pcap_t for a ``savefile'', given a FILE *, and
335 specify the precision to provide for packet time stamps
336 pcap_open_dead(3PCAP)
338 create a ``fake'' pcap_t
339 pcap_close(3PCAP)
341 close a pcap_t
342 pcap_set_snaplen(3PCAP)
344 set the snapshot length for a not-yet-activated pcap_t
345 for live capture
346 pcap_snapshot(3PCAP)
348 get the snapshot length for a pcap_t
349 pcap_set_promisc(3PCAP)
351 set promiscuous mode for a not-yet-activated pcap_t for
352 live capture
353 pcap_set_protocol_linux(3PCAP)
355 set capture protocol for a not-yet-activated pcap_t for
356 live capture (Linux only)
357 pcap_set_rfmon(3PCAP)
359 set monitor mode for a not-yet-activated pcap_t for live
360 capture
361 pcap_can_set_rfmon(3PCAP)
363 determine whether monitor mode can be set for a pcap_t
364 for live capture
365 pcap_set_timeout(3PCAP)
367 set packet buffer timeout for a not-yet-activated pcap_t
368 for live capture
369 pcap_set_immediate_mode(3PCAP)
371 set immediate mode for a not-yet-activated pcap_t for
372 live capture
373 pcap_set_buffer_size(3PCAP)
375 set buffer size for a not-yet-activated pcap_t for live
376 capture
377 pcap_set_tstamp_type(3PCAP)
379 set time stamp type for a not-yet-activated pcap_t for
380 live capture
381 pcap_list_tstamp_types(3PCAP)
383 get list of available time stamp types for a not-yet-
384 activated pcap_t for live capture
385 pcap_free_tstamp_types(3PCAP)
387 free list of available time stamp types
388 pcap_tstamp_type_val_to_name(3PCAP)
390 get name for a time stamp type
391 pcap_tstamp_type_val_to_description(3PCAP)
393 get description for a time stamp type
394 pcap_tstamp_type_name_to_val(3PCAP)
396 get time stamp type corresponding to a name
397 pcap_set_tstamp_precision(3PCAP)
399 set time stamp precision for a not-yet-activated pcap_t
400 for live capture
401 pcap_get_tstamp_precision(3PCAP)
403 get the time stamp precision of a pcap_t for live capture
404 pcap_datalink(3PCAP)
406 get link-layer header type for a pcap_t
407 pcap_file(3PCAP)
409 get the FILE * for a pcap_t opened for a ``savefile''
410 pcap_is_swapped(3PCAP)
412 determine whether a ``savefile'' being read came from a
413 machine with the opposite byte order
414 pcap_major_version(3PCAP)
416 pcap_minor_version(3PCAP)
417 get the major and minor version of the file format ver‐
418 sion for a ``savefile''
419 Selecting a link-layer header type for a live capture
421 Some devices may provide more than one link-layer header type. To
422 obtain a list of all link-layer header types provided by a device, call
423 pcap_list_datalinks() on an activated pcap_t for the device. To free a
424 list of link-layer header types, call pcap_free_datalinks(). To set
425 the link-layer header type for a device, call pcap_set_datalink().
426 This should be done after the device has been activated but before any
427 packets are read and before any filters are compiled or installed.
428 Routines
430 pcap_list_datalinks(3PCAP)
432 get a list of link-layer header types for a device
433 pcap_free_datalinks(3PCAP)
435 free list of link-layer header types
436 pcap_set_datalink(3PCAP)
438 set link-layer header type for a device
439 pcap_datalink_val_to_name(3PCAP)
441 get name for a link-layer header type
442 pcap_datalink_val_to_description(3PCAP)
444 pcap_datalink_val_to_description_or_dlt(3PCAP)
445 get description for a link-layer header type
446 pcap_datalink_name_to_val(3PCAP)
448 get link-layer header type corresponding to a name
449 Reading packets
451 Packets are read with pcap_dispatch() or pcap_loop(), which process one
452 or more packets, calling a callback routine for each packet, or with
453 pcap_next() or pcap_next_ex(), which return the next packet. The call‐
454 back for pcap_dispatch() and pcap_loop() is supplied a pointer to a
455 struct pcap_pkthdr, which includes the following members:
456 ts a struct timeval containing the time when the packet was
458 captured
459 caplen a bpf_u_int32 giving the number of bytes of the packet
461 that are available from the capture
462 len a bpf_u_int32 giving the length of the packet, in bytes
464 (which might be more than the number of bytes available
465 from the capture, if the length of the packet is larger
466 than the maximum number of bytes to capture).
467 The callback is also supplied a const u_char pointer to the first
469 caplen (as given in the struct pcap_pkthdr mentioned above) bytes of
470 data from the packet. This won't necessarily be the entire packet; to
471 capture the entire packet, you will have to provide a value for snaplen
472 in your call to pcap_set_snaplen() that is sufficiently large to get
473 all of the packet's data - a value of 65535 should be sufficient on
474 most if not all networks). When reading from a ``savefile'', the snap‐
475 shot length specified when the capture was performed will limit the
476 amount of packet data available.
477 pcap_next() is passed an argument that points to a struct pcap_pkthdr
479 structure, and fills it in with the time stamp and length values for
480 the packet. It returns a const u_char to the first caplen bytes of the
481 packet on success, and NULL on error.
482 pcap_next_ex() is passed two pointer arguments, one of which points to
484 a structpcap_pkthdr* and one of which points to a const u_char*. It
485 sets the first pointer to point to a struct pcap_pkthdr structure with
486 the time stamp and length values for the packet, and sets the second
487 pointer to point to the first caplen bytes of the packet.
488 To force the loop in pcap_dispatch() or pcap_loop() to terminate, call
490 pcap_breakloop().
491 By default, when reading packets from an interface opened for a live
493 capture, pcap_dispatch(), pcap_next(), and pcap_next_ex() will, if no
494 packets are currently available to be read, block waiting for packets
495 to become available. On some, but not all, platforms, if a packet buf‐
496 fer timeout was specified, the wait will terminate after the packet
497 buffer timeout expires; applications should be prepared for this, as it
498 happens on some platforms, but should not rely on it, as it does not
499 happen on other platforms. Note that the wait might, or might not,
500 terminate even if no packets are available; applications should be pre‐
501 pared for this to happen, but must not rely on it happening.
502 A handle can be put into ``non-blocking mode'', so that those routines
504 will, rather than blocking, return an indication that no packets are
505 available to read. Call pcap_setnonblock() to put a handle into non-
506 blocking mode or to take it out of non-blocking mode; call pcap_getnon‐
507 block() to determine whether a handle is in non-blocking mode. Note
508 that non-blocking mode does not work correctly in Mac OS X 10.6.
509 Non-blocking mode is often combined with routines such as select(2) or
511 poll(2) or other routines a platform offers to wait for any of a set of
512 descriptors to be ready to read. To obtain, for a handle, a descriptor
513 that can be used in those routines, call pcap_get_selectable_fd(). If
514 the routine indicates that data is available to read on the descriptor,
515 an attempt should be made to read from the device.
516 Not all handles have such a descriptor available;
518 pcap_get_selectable_fd() will return -1 if no such descriptor is avail‐
519 able. If no such descriptor is available, this may be because the
520 device must be polled periodically for packets; in that case,
521 pcap_get_required_select_timeout() will return a pointer to a struct
522 timeval whose value can be used as a timeout in those routines. When
523 the routine returns, an attmept should be made to read packets from the
524 device. If pcap_get_required_select_timeout() returns NULL, no such
525 timeout is available, and those routines cannot be used with the
526 device.
527 In addition, for various reasons, one or more of those routines will
529 not work properly with the descriptor; the documentation for
530 pcap_get_selectable_fd() gives details. Note that, just as an attempt
531 to read packets from a pcap_t may not return any packets if the packet
532 buffer timeout expires, a select(), poll(), or other such call may, if
533 the packet buffer timeout expires, indicate that a descriptor is ready
534 to read even if there are no packets available to read.
535 Routines
537 pcap_dispatch(3PCAP)
539 read a bufferful of packets from a pcap_t open for a live
540 capture or the full set of packets from a pcap_t open for
541 a ``savefile''
542 pcap_loop(3PCAP)
544 read packets from a pcap_t until an interrupt or error
545 occurs
546 pcap_next(3PCAP)
548 read the next packet from a pcap_t without an indication
549 whether an error occurred
550 pcap_next_ex(3PCAP)
552 read the next packet from a pcap_t with an error indica‐
553 tion on an error
554 pcap_breakloop(3PCAP)
556 prematurely terminate the loop in pcap_dispatch() or
557 pcap_loop()
558 pcap_setnonblock(3PCAP)
560 set or clear non-blocking mode on a pcap_t
561 pcap_getnonblock(3PCAP)
563 get the state of non-blocking mode for a pcap_t
564 pcap_get_selectable_fd(3PCAP)
566 attempt to get a descriptor for a pcap_t that can be used
567 in calls such as select(2) and poll(2)
568 pcap_get_required_select_timeout(3PCAP)
570 attempt to get a timeout required for using a pcap_t in
571 calls such as select(2) and poll(2)
572 Filters
574 In order to cause only certain packets to be returned when reading
575 packets, a filter can be set on a handle. For a live capture, the fil‐
576 tering will be performed in kernel mode, if possible, to avoid copying
577 ``uninteresting'' packets from the kernel to user mode.
578 A filter can be specified as a text string; the syntax and semantics of
580 the string are as described by pcap-filter(7). A filter string is com‐
581 piled into a program in a pseudo-machine-language by pcap_compile() and
582 the resulting program can be made a filter for a handle with pcap_set‐
583 filter(). The result of pcap_compile() can be freed with a call to
584 pcap_freecode(). pcap_compile() may require a network mask for certain
585 expressions in the filter string; pcap_lookupnet() can be used to find
586 the network address and network mask for a given capture device.
587 A compiled filter can also be applied directly to a packet that has
589 been read using pcap_offline_filter().
590 Routines
592 pcap_compile(3PCAP)
594 compile filter expression to a pseudo-machine-language
595 code program
596 pcap_freecode(3PCAP)
598 free a filter program
599 pcap_setfilter(3PCAP)
601 set filter for a pcap_t
602 pcap_lookupnet(3PCAP)
604 get network address and network mask for a capture device
605 pcap_offline_filter(3PCAP)
607 apply a filter program to a packet
608 Incoming and outgoing packets
610 By default, libpcap will attempt to capture both packets sent by the
611 machine and packets received by the machine. To limit it to capturing
612 only packets received by the machine or, if possible, only packets sent
613 by the machine, call pcap_setdirection().
614 Routines
616 pcap_setdirection(3PCAP)
618 specify whether to capture incoming packets, outgoing
619 packets, or both
620 Capture statistics
622 To get statistics about packets received and dropped in a live capture,
623 call pcap_stats().
624 Routines
626 pcap_stats(3PCAP)
628 get capture statistics
629 Opening a handle for writing captured packets
631 To open a ``savefile`` to which to write packets, given the pathname
632 the ``savefile'' should have, call pcap_dump_open(). To open a ``save‐
633 file`` to which to write packets, given the pathname the ``savefile''
634 should have, call pcap_dump_open(); to set up a handle for a ``save‐
635 file'', given a FILE * referring to a file already opened for writing,
636 call pcap_dump_fopen(). They each return pointers to a pcap_dumper_t,
637 which is the handle used for writing packets to the ``savefile''. If
638 it succeeds, it will have created the file if it doesn't exist and
639 truncated the file if it does exist. To close a pcap_dumper_t, call
640 pcap_dump_close().
641 Routines
643 pcap_dump_open(3PCAP)
645 open a pcap_dumper_t for a ``savefile``, given a pathname
646 pcap_dump_fopen(3PCAP)
648 open a pcap_dumper_t for a ``savefile``, given a FILE *
649 pcap_dump_close(3PCAP)
651 close a pcap_dumper_t
652 pcap_dump_file(3PCAP)
654 get the FILE * for a pcap_dumper_t opened for a ``save‐
655 file''
656 Writing packets
658 To write a packet to a pcap_dumper_t, call pcap_dump(). Packets writ‐
659 ten with pcap_dump() may be buffered, rather than being immediately
660 written to the ``savefile''. Closing the pcap_dumper_t will cause all
661 buffered-but-not-yet-written packets to be written to the ``savefile''.
662 To force all packets written to the pcap_dumper_t, and not yet written
663 to the ``savefile'' because they're buffered by the pcap_dumper_t, to
664 be written to the ``savefile'', without closing the pcap_dumper_t, call
665 pcap_dump_flush().
666 Routines
668 pcap_dump(3PCAP)
670 write packet to a pcap_dumper_t
671 pcap_dump_flush(3PCAP)
673 flush buffered packets written to a pcap_dumper_t to the
674 ``savefile''
675 pcap_dump_ftell(3PCAP)
677 get current file position for a pcap_dumper_t
678 Injecting packets
680 If you have the required privileges, you can inject packets onto a net‐
681 work with a pcap_t for a live capture, using pcap_inject() or
682 pcap_sendpacket(). (The two routines exist for compatibility with both
683 OpenBSD and WinPcap/Npcap; they perform the same function, but have
684 different return values.)
685 Routines
687 pcap_inject(3PCAP)
689 pcap_sendpacket(3PCAP)
690 transmit a packet
691 Reporting errors
693 Some routines return error or warning status codes; to convert them to
694 a string, use pcap_statustostr().
695 Routines
697 pcap_statustostr(3PCAP)
699 get a string for an error or warning status code
700 Getting library version information
702 To get a string giving version information about libpcap, call
703 pcap_lib_version().
704 Routines
706 pcap_lib_version(3PCAP)
708 get library version string
709
711 In versions of libpcap prior to 1.0, the pcap.h header file was not in
712 a pcap directory on most platforms; if you are writing an application
713 that must work on versions of libpcap prior to 1.0, include <pcap.h>,
714 which will include <pcap/pcap.h> for you, rather than including
715 <pcap/pcap.h>.
716 pcap_create() and pcap_activate() were not available in versions of
718 libpcap prior to 1.0; if you are writing an application that must work
719 on versions of libpcap prior to 1.0, either use pcap_open_live() to get
720 a handle for a live capture or, if you want to be able to use the addi‐
721 tional capabilities offered by using pcap_create() and pcap_activate(),
722 use an autoconf(1) script or some other configuration script to check
723 whether the libpcap 1.0 APIs are available and use them only if they
724 are.
725
727 autoconf(1), tcpdump(8), tcpslice(8), pcap-filter(7), pfconfig(8),
728 usermod(8)
729
731 The original authors of libpcap are:
732 Van Jacobson, Craig Leres and Steven McCanne, all of the Lawrence
734 Berkeley National Laboratory, University of California, Berkeley, CA.
735 The current version is available from "The Tcpdump Group"'s Web site at
737 https://www.tcpdump.org/
739
741 To report a security issue please send an e-mail to security@tcp‐
742 dump.org.
743 To report bugs and other problems, contribute patches, request a fea‐
745 ture, provide generic feedback etc please see the file CONTRIBUTING.md
746 in the libpcap source tree root.
747 9 September 2020 PCAP(3PCAP)