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 op‐
20 tions; 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 al‐
36 ways 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 "Ra‐
135 dio Frequency MONitor"), the adapter will supply all frames that
136 it receives, with 802.11 headers, and might supply a pseudo-
137 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 pcap_can_set_rf‐
147 mon() can be used to determine whether an adapter can be put
148 into monitor mode.
149 packet buffer timeout
151 If, when capturing, packets are delivered as soon as they ar‐
152 rive, the application capturing the packets will be woken up for
153 each packet as it arrives, and might have to make one or more
154 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, be‐
181 cause, 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 ap‐
185 plication to allow the packet capture loop to ``poll'' for user
186 input periodically, as there's no guarantee that a call reading
187 packets will return after the timeout expires even if no packets
188 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 or‐
260 der 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 in‐
265 terface unless the super-user has enabled promiscuous-mode oper‐
266 ation on that interface using pfconfig(8), and no user (not even
267 the super-user) can capture unicast traffic received by or sent
268 by the machine on an interface unless the super-user has enabled
269 copy-all-mode operation on that interface using pfconfig, so
270 useful packet capture on an interface probably requires that ei‐
271 ther promiscuous-mode or copy-all-mode operation, or both modes
272 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 in‐
280 volve configuring devfs to set the ownership or permissions ev‐
281 ery time the system is booted, if the system even supports that;
282 if it doesn't support that, you might have to find some other
283 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 in‐
290 terfaces. To determine the format of the packets supplied by the han‐
291 dle, call pcap_datalink(); https://www.tcpdump.org/linktypes.html lists
292 the values it returns and describes the packet formats that correspond
293 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-ac‐
384 tivated 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 ob‐
422 tain 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; pcap_get_se‐
518 lectable_fd() will return -1 if no such descriptor is available. If no
519 such descriptor is available, this may be because the device must be
520 polled periodically for packets; in that case, pcap_get_required_se‐
521 lect_timeout() will return a pointer to a struct timeval whose value
522 can be used as a timeout in those routines. When the routine returns,
523 an attempt should be made to read packets from the device. If
524 pcap_get_required_select_timeout() returns NULL, no such timeout is
525 available, and those routines cannot be used with the device.
526 In addition, for various reasons, one or more of those routines will
528 not work properly with the descriptor; the documentation for
529 pcap_get_selectable_fd() gives details. Note that, just as an attempt
530 to read packets from a pcap_t may not return any packets if the packet
531 buffer timeout expires, a select(), poll(), or other such call may, if
532 the packet buffer timeout expires, indicate that a descriptor is ready
533 to read even if there are no packets available to read.
534 Routines
536 pcap_dispatch(3PCAP)
538 read a bufferful of packets from a pcap_t open for a live
539 capture or the full set of packets from a pcap_t open for
540 a ``savefile''
541 pcap_loop(3PCAP)
543 read packets from a pcap_t until an interrupt or error
544 occurs
545 pcap_next(3PCAP)
547 read the next packet from a pcap_t without an indication
548 whether an error occurred
549 pcap_next_ex(3PCAP)
551 read the next packet from a pcap_t with an error indica‐
552 tion on an error
553 pcap_breakloop(3PCAP)
555 prematurely terminate the loop in pcap_dispatch() or
556 pcap_loop()
557 pcap_setnonblock(3PCAP)
559 set or clear non-blocking mode on a pcap_t
560 pcap_getnonblock(3PCAP)
562 get the state of non-blocking mode for a pcap_t
563 pcap_get_selectable_fd(3PCAP)
565 attempt to get a descriptor for a pcap_t that can be used
566 in calls such as select() and poll()
567 pcap_get_required_select_timeout(3PCAP)
569 attempt to get a timeout required for using a pcap_t in
570 calls such as select() and poll()
571 Filters
573 In order to cause only certain packets to be returned when reading
574 packets, a filter can be set on a handle. For a live capture, the fil‐
575 tering will be performed in kernel mode, if possible, to avoid copying
576 ``uninteresting'' packets from the kernel to user mode.
577 A filter can be specified as a text string; the syntax and semantics of
579 the string are as described by pcap-filter(7). A filter string is com‐
580 piled into a program in a pseudo-machine-language by pcap_compile() and
581 the resulting program can be made a filter for a handle with pcap_set‐
582 filter(). The result of pcap_compile() can be freed with a call to
583 pcap_freecode(). pcap_compile() may require a network mask for certain
584 expressions in the filter string; pcap_lookupnet() can be used to find
585 the network address and network mask for a given capture device.
586 A compiled filter can also be applied directly to a packet that has
588 been read using pcap_offline_filter().
589 Routines
591 pcap_compile(3PCAP)
593 compile filter expression to a pseudo-machine-language
594 code program
595 pcap_freecode(3PCAP)
597 free a filter program
598 pcap_setfilter(3PCAP)
600 set filter for a pcap_t
601 pcap_lookupnet(3PCAP)
603 get network address and network mask for a capture device
604 pcap_offline_filter(3PCAP)
606 apply a filter program to a packet
607 Incoming and outgoing packets
609 By default, libpcap will attempt to capture both packets sent by the
610 machine and packets received by the machine. To limit it to capturing
611 only packets received by the machine or, if possible, only packets sent
612 by the machine, call pcap_setdirection().
613 Routines
615 pcap_setdirection(3PCAP)
617 specify whether to capture incoming packets, outgoing
618 packets, or both
619 Capture statistics
621 To get statistics about packets received and dropped in a live capture,
622 call pcap_stats().
623 Routines
625 pcap_stats(3PCAP)
627 get capture statistics
628 Opening a handle for writing captured packets
630 To open a ``savefile`` to which to write packets, given the pathname
631 the ``savefile'' should have, call pcap_dump_open(). To open a ``save‐
632 file`` to which to write packets, given the pathname the ``savefile''
633 should have, call pcap_dump_open(); to set up a handle for a ``save‐
634 file'', given a FILE * referring to a file already opened for writing,
635 call pcap_dump_fopen(). They each return pointers to a pcap_dumper_t,
636 which is the handle used for writing packets to the ``savefile''. If
637 it succeeds, it will have created the file if it doesn't exist and
638 truncated the file if it does exist. To close a pcap_dumper_t, call
639 pcap_dump_close().
640 Routines
642 pcap_dump_open(3PCAP)
644 open a pcap_dumper_t for a ``savefile``, given a path‐
645 name, replacing any existing data
646 pcap_dump_open_append(3PCAP)
648 open a pcap_dumper_t for a ``savefile``, given a path‐
649 name, appending to the existing data
650 pcap_dump_fopen(3PCAP)
652 open a pcap_dumper_t for a ``savefile``, given a FILE *,
653 assuming an empty file
654 pcap_dump_close(3PCAP)
656 close a pcap_dumper_t
657 pcap_dump_file(3PCAP)
659 get the FILE * for a pcap_dumper_t opened for a ``save‐
660 file''
661 Writing packets
663 To write a packet to a pcap_dumper_t, call pcap_dump(). Packets writ‐
664 ten with pcap_dump() may be buffered, rather than being immediately
665 written to the ``savefile''. Closing the pcap_dumper_t will cause all
666 buffered-but-not-yet-written packets to be written to the ``savefile''.
667 To force all packets written to the pcap_dumper_t, and not yet written
668 to the ``savefile'' because they're buffered by the pcap_dumper_t, to
669 be written to the ``savefile'', without closing the pcap_dumper_t, call
670 pcap_dump_flush().
671 Routines
673 pcap_dump(3PCAP)
675 write packet to a pcap_dumper_t
676 pcap_dump_flush(3PCAP)
678 flush buffered packets written to a pcap_dumper_t to the
679 ``savefile''
680 pcap_dump_ftell(3PCAP)
682 get current file position for a pcap_dumper_t
683 Injecting packets
685 If you have the required privileges, you can inject packets onto a net‐
686 work with a pcap_t for a live capture, using pcap_inject() or
687 pcap_sendpacket(). (The two routines exist for compatibility with both
688 OpenBSD and WinPcap/Npcap; they perform the same function, but have
689 different return values.)
690 Routines
692 pcap_inject(3PCAP)
694 pcap_sendpacket(3PCAP)
695 transmit a packet
696 Reporting errors
698 Some routines return error or warning status codes; to convert them to
699 a string, use pcap_statustostr().
700 Routines
702 pcap_statustostr(3PCAP)
704 get a string for an error or warning status code
705 Getting library version information
707 To get a string giving version information about libpcap, call
708 pcap_lib_version().
709 Routines
711 pcap_lib_version(3PCAP)
713 get library version string
714
716 In versions of libpcap prior to 1.0, the pcap.h header file was not in
717 a pcap directory on most platforms; if you are writing an application
718 that must work on versions of libpcap prior to 1.0, include <pcap.h>,
719 which will include <pcap/pcap.h> for you, rather than including
720 <pcap/pcap.h>.
721 pcap_create() and pcap_activate() were not available in versions of
723 libpcap prior to 1.0; if you are writing an application that must work
724 on versions of libpcap prior to 1.0, either use pcap_open_live() to get
725 a handle for a live capture or, if you want to be able to use the addi‐
726 tional capabilities offered by using pcap_create() and pcap_activate(),
727 use an autoconf(1) script or some other configuration script to check
728 whether the libpcap 1.0 APIs are available and use them only if they
729 are.
730
732 autoconf(1), tcpdump(8), tcpslice(8), pcap-filter(7), pfconfig(8),
733 usermod(8)
734
736 The original authors of libpcap are:
737 Van Jacobson, Craig Leres and Steven McCanne, all of the Lawrence
739 Berkeley National Laboratory, University of California, Berkeley, CA.
740 The current version is available from "The Tcpdump Group"'s Web site at
742 https://www.tcpdump.org/
744
746 To report a security issue please send an e-mail to
747 security@tcpdump.org.
748 To report bugs and other problems, contribute patches, request a fea‐
750 ture, provide generic feedback etc please see the file CONTRIBUTING.md
751 in the libpcap source tree root.
752 9 September 2020 PCAP(3PCAP)