--- name: "pcap" section: "3pcap" platform: "linux" package: "libpcap" version: "1.11.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "macos"] url: "https://new.carta.tech/pcap/3pcap" --- # pcap(3pcap) Packet Capture library ## NAME pcap - Packet Capture library ## SYNOPSIS ``` #include ``` ## DESCRIPTION **The Packet Capture library** **provides a high level interface to packet capture systems. All packets** **on the network, even those destined for other hosts, are accessible** **through this mechanism.** **It also supports saving captured packets to a \`\`savefile'', and reading** **packets from a \`\`savefile''.** ### Initializing **pcap\_init**() **initializes the library. It takes an argument giving options;** **currently, the options are:** - **PCAP\_CHAR\_ENC\_LOCAL** **Treat all strings supplied as arguments, and return all strings to the** **caller, as being in the local character encoding.** - **PCAP\_CHAR\_ENC\_UTF\_8** **Treat all strings supplied as arguments, and return all strings to the** **caller, as being in UTF-8.** **On UNIX-like systems, the local character encoding is assumed to be** **UTF-8, so no character encoding transformations are done.** **On Windows, the local character encoding is the local ANSI code page.** **If** **pcap\_init**() **is called, the deprecated** **pcap\_lookupdev**() **routine always fails, so it should not be used, and, on Windows,** **pcap\_create**() **does not attempt to handle UTF-16LE strings.** **If** **pcap\_init**() **is not called, strings are treated as being in the local ANSI code page** **on Windows,** **pcap\_lookupdev**() **will succeed if there is a device on which to capture, and** **pcap\_create**() **makes an attempt to check whether the string passed as an argument is a** **UTF-16LE string - note that this attempt is unsafe, as it may run past** **the end of the string - to handle** **pcap\_lookupdev**() **returning a UTF-16LE string.** - **Routines** - **pcap\_init**(3PCAP) **initialize the library** ### Opening a capture handle for reading **To open a handle for a live capture, given the name of the network or** **other interface on which the capture should be done, call** **pcap\_create**(), **set the appropriate options on the handle, and then activate it with** **pcap\_activate**(). **If** **pcap\_activate**() **fails, the handle should be closed with** **pcap\_close**(). **To obtain a list of devices that can be opened for a live capture, call** **pcap\_findalldevs**(); **to free the list returned by** **pcap\_findalldevs**(), **call** **pcap\_freealldevs**(). **pcap\_lookupdev**() **will return the first device on that list that is not a \`\`loopback\`\`** **network interface.** **To open a handle for a \`\`savefile'' from which to read packets, given the** **pathname of the \`\`savefile'', call** **pcap\_open\_offline**(); **to set up a handle for a \`\`savefile'', given a** **FILE \*** **referring to a file already opened for reading, call** **pcap\_fopen\_offline**(). **In order to get a \`\`fake''** **pcap\_t** **for use in routines that require a** **pcap\_t** **as an argument, such as routines to open a \`\`savefile'' for writing and** **to compile a filter expression, call** **pcap\_open\_dead**(). **pcap\_create**(), **pcap\_open\_offline**(), **pcap\_fopen\_offline**(), **and** **pcap\_open\_dead**() **return a pointer to a** **pcap\_t**, **which is the handle used for reading packets from the capture stream or** **the \`\`savefile'', and for finding out information about the capture** **stream or \`\`savefile''.** **To close a handle, use** **pcap\_close**(). **The options that can be set on a capture handle include** - snapshot length **If, when capturing, you capture the entire contents of the packet, that** **requires more CPU time to copy the packet to your application, more disk** **and possibly network bandwidth to write the packet data to a file, and** **more disk space to save the packet. If you don't need the entire** **contents of the packet - for example, if you are only interested in the** **TCP headers of packets - you can set the "snapshot length" for the** **capture to an appropriate value. If the snapshot length is set to** *snaplen*, **and** *snaplen* **is less** **than the size of a packet that is captured, only the first** *snaplen* **bytes of that packet will be captured and provided as packet data.** - **A snapshot length of 65535 should be sufficient, on most if not all** **networks, to capture all the data available from the packet.** - **The snapshot length is set with** **pcap\_set\_snaplen**(). - promiscuous mode **On broadcast LANs such as Ethernet, if the network isn't switched, or if** **the adapter is connected to a "mirror port" on a switch to which all** **packets passing through the switch are sent, a network adapter receives** **all packets on the LAN, including unicast or multicast packets not sent** **to a network address that the network adapter isn't configured to** **recognize.** - **Normally, the adapter will discard those packets; however, many network** **adapters support "promiscuous mode", which is a mode in which all** **packets, even if they are not sent to an address that the adapter** **recognizes, are provided to the host. This is useful for passively** **capturing traffic between two or more other hosts for analysis.** - **Note that even if an application does not set promiscuous mode, the** **adapter could well be in promiscuous mode for some other reason.** - **For now, this doesn't work on the "any" device; if an argument of "any"** **or** **a null pointer** **is supplied, the setting of promiscuous mode is ignored.** - **Promiscuous mode is set with** **pcap\_set\_promisc**(). - monitor mode **On IEEE 802.11 wireless LANs, even if an adapter is in promiscuous mode,** **it will supply to the host only frames for the network with which it's** **associated. It might also supply only data frames, not management or** **control frames, and might not provide the 802.11 header or radio** **information pseudo-header for those frames.** - **In "monitor mode", sometimes also called "rfmon mode" (for "Radio** **Frequency MONitor"), the adapter will supply all frames that it** **receives, with 802.11 headers, and might supply a pseudo-header with** **radio information about the frame as well.** - **Note that in monitor mode the adapter might disassociate from the** **network with which it's associated, so that you will not be able to use** **any wireless networks with that adapter. This could prevent accessing** **files on a network server, or resolving host names or network addresses,** **if you are capturing in monitor mode and are not connected to another** **network with another adapter.** - **Monitor mode is set with** **pcap\_set\_rfmon**(), **and** **pcap\_can\_set\_rfmon**() **can be used to determine whether an adapter can be put into monitor** **mode.** - packet buffer timeout **If, when capturing, packets are delivered as soon as they arrive, the** **application capturing the packets will be woken up for each packet as it** **arrives, and might have to make one or more calls to the operating** **system to fetch each packet.** - **If, instead, packets are not delivered as soon as they arrive, but are** **delivered after a short delay (called a "packet buffer timeout"), more** **than one packet can be accumulated before the packets are delivered, so** **that a single wakeup would be done for multiple packets, and each set of** **calls made to the operating system would supply multiple packets, rather** **than a single packet. This reduces the per-packet CPU overhead if** **packets are arriving at a high rate, increasing the number of packets** **per second that can be captured.** - **The packet buffer timeout is required so that an application won't wait** **for the operating system's capture buffer to fill up before packets are** **delivered; if packets are arriving slowly, that wait could take an** **arbitrarily long period of time.** - **Not all platforms support a packet buffer timeout; on platforms that** **don't, the packet buffer timeout is ignored. A zero value for the** **timeout, on platforms that support a packet buffer timeout, will cause a** **read to wait forever to allow enough packets to arrive, with no timeout.** **A negative value is invalid; the result of setting the timeout to a** **negative value is unpredictable.** - **NOTE**: **the packet buffer timeout cannot be used to cause calls that read** **packets to return within a limited period of time, because, on some** **platforms, the packet buffer timeout isn't supported, and, on other** **platforms, the timer doesn't start until at least one packet arrives.** **This means that the packet buffer timeout should** **NOT** **be used, for example, in an interactive application to allow the packet** **capture loop to \`\`poll'' for user input periodically, as there's no** **guarantee that a call reading packets will return after the timeout** **expires even if no packets have arrived.** - **The packet buffer timeout is set with** **pcap\_set\_timeout**(). - immediate mode **In immediate mode, packets are always delivered as soon as they arrive,** **with no buffering. Immediate mode is set with** **pcap\_set\_immediate\_mode**(). - buffer size **Packets that arrive for a capture are stored in a buffer, so that they** **do not have to be read by the application as soon as they arrive. On** **some platforms, the buffer's size can be set; a size that's too small** **could mean that, if too many packets are being captured and the snapshot** **length doesn't limit the amount of data that's buffered, packets could** **be dropped if the buffer fills up before the application can read** **packets from it, while a size that's too large could use more** **non-pageable operating system memory than is necessary to prevent** **packets from being dropped.** - **The buffer size is set with** **pcap\_set\_buffer\_size**(). - timestamp type **On some platforms, the time stamp given to packets on live captures can** **come from different sources that can have different resolutions or that** **can have different relationships to the time values for the current time** **supplied by routines on the native operating system. See** [**pcap-tstamp**(7)](/pcap-tstamp/7.md) **for a list of time stamp types.** - **The time stamp type is set with** **pcap\_set\_tstamp\_type**(). **Reading packets from a network interface may require that you have** **special privileges:** - **Under Solaris with DLPI:** **You must have read/write access to the network pseudo device, e.g.** */dev/le*. **On at least some versions of Solaris, however, this is not sufficient to** **allow** *tcpdump* **to capture in promiscuous mode; on those versions of Solaris, you must** **be root, or the application capturing packets** **must be installed setuid to root, in order to capture in promiscuous** **mode. Note that, on many (perhaps all) interfaces, if you don't capture** **in promiscuous mode, you will not see any outgoing packets, so a capture** **not done in promiscuous mode may not be very useful.** - **In newer versions of Solaris, you must have been given the** **net\_rawaccess** **privilege; this is both necessary and sufficient to give you access to the** **network pseudo-device - there is no need to change the privileges on** **that device. A user can be given that privilege by, for example, adding** **that privilege to the user's** **defaultpriv** **key with the** [**usermod**(8)](/usermod/8.md) **command.** - **Under HP-UX with DLPI:** **You must be root or the application capturing packets must be installed** **setuid to root.** - **Under Linux:** **You must be root or the application capturing packets must be installed** **setuid to root, unless your distribution has a kernel** **that supports capability bits such as** **CAP\_NET\_RAW** **and code to allow** **those capability bits to be given to particular accounts and to cause** **those bits to be set on a user's initial processes when they log in, in** **which case you must have** **CAP\_NET\_RAW** **in order to capture.** - **Under BSD (this includes macOS):** **You must have read access to** */dev/bpf\** **on systems that don't have a cloning BPF device, or to** */dev/bpf* **on systems that do.** **On BSDs with a devfs (this includes macOS), this might involve more** **than just having somebody with super-user access setting the ownership** **or permissions on the BPF devices - it might involve configuring devfs** **to set the ownership or permissions every time the system is booted,** **if the system even supports that; if it doesn't support that, you might** **have to find some other way to make that happen at boot time.** **Reading a saved packet file doesn't require special privileges.** **The packets read from the handle may include a \`\`pseudo-header''** **containing various forms of packet meta-data, and probably includes a** **link-layer header whose contents can differ for different network** **interfaces. To determine the format of the packets supplied by the** **handle, call** **pcap\_datalink**(); *https://www.tcpdump.org/linktypes.html* **lists the values it returns and describes the packet formats that** **correspond to those values.** **Do** **NOT** **assume that the packets for a given capture or \`\`savefile\`\` will have** **any given link-layer header type, such as** **DLT\_EN10MB** **for Ethernet. For example, the "any" device on Linux will have a** **link-layer header type of** **DLT\_LINUX\_SLL** **or** **DLT\_LINUX\_SLL2** **even if all devices on the system at the time the "any" device is opened** **have some other data link type, such as** **DLT\_EN10MB** **for Ethernet.** **To obtain the** **FILE \*** **corresponding to a** **pcap\_t** **opened for a \`\`savefile'', call** **pcap\_file**(). - **Routines** - **pcap\_create**(3PCAP) **get a** **pcap\_t** **for live capture** - **pcap\_activate**(3PCAP) **activate a** **pcap\_t** **for live capture** - **pcap\_findalldevs**(3PCAP) **get a list of devices that can be opened for a live capture** - **pcap\_freealldevs**(3PCAP) **free list of devices** - **pcap\_lookupdev**(3PCAP) **get first non-loopback device on that list** - **pcap\_open\_offline**(3PCAP) **open a** **pcap\_t** **for a \`\`savefile'', given a pathname** - **pcap\_open\_offline\_with\_tstamp\_precision**(3PCAP) **open a** **pcap\_t** **for a \`\`savefile'', given a pathname, and specify the precision to** **provide for packet time stamps** - **pcap\_fopen\_offline**(3PCAP) **open a** **pcap\_t** **for a \`\`savefile'', given a** **FILE \*** - **pcap\_fopen\_offline\_with\_tstamp\_precision**(3PCAP) **open a** **pcap\_t** **for a \`\`savefile'', given a** **FILE \***, **and specify the precision to provide for packet time stamps** - **pcap\_open\_dead**(3PCAP) **create a \`\`fake''** **pcap\_t** - **pcap\_close**(3PCAP) **close a** **pcap\_t** - **pcap\_set\_snaplen**(3PCAP) **set the snapshot length for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_snapshot**(3PCAP) **get the snapshot length for a** **pcap\_t** - **pcap\_set\_promisc**(3PCAP) **set promiscuous mode for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_set\_protocol\_linux**(3PCAP) **set capture protocol for a not-yet-activated** **pcap\_t** **for live capture (Linux only)** - **pcap\_set\_rfmon**(3PCAP) **set monitor mode for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_can\_set\_rfmon**(3PCAP) **determine whether monitor mode can be set for a** **pcap\_t** **for live capture** - **pcap\_set\_timeout**(3PCAP) **set packet buffer timeout for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_set\_immediate\_mode**(3PCAP) **set immediate mode for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_set\_buffer\_size**(3PCAP) **set buffer size for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_set\_tstamp\_type**(3PCAP) **set time stamp type for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_list\_tstamp\_types**(3PCAP) **get list of available time stamp types for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_free\_tstamp\_types**(3PCAP) **free list of available time stamp types** - **pcap\_tstamp\_type\_val\_to\_name**(3PCAP) **get name for a time stamp type** - **pcap\_tstamp\_type\_val\_to\_description**(3PCAP) **get description for a time stamp type** - **pcap\_tstamp\_type\_name\_to\_val**(3PCAP) **get time stamp type corresponding to a name** - **pcap\_set\_tstamp\_precision**(3PCAP) **set time stamp precision for a not-yet-activated** **pcap\_t** **for live capture** - **pcap\_get\_tstamp\_precision**(3PCAP) **get the time stamp precision of a** **pcap\_t** **for live capture** - **pcap\_datalink**(3PCAP) **get link-layer header type for a** **pcap\_t** - **pcap\_file**(3PCAP) **get the** **FILE \*** **for a** **pcap\_t** **opened for a \`\`savefile''** - **pcap\_is\_swapped**(3PCAP) **determine whether a \`\`savefile'' being read came from a machine with the** **opposite byte order** - **pcap\_major\_version**(3PCAP) - **pcap\_minor\_version**(3PCAP) **get the major and minor version of the file format version for a** **\`\`savefile''** ### Selecting a link-layer header type for a live capture **Some devices may provide more than one link-layer header type. To** **obtain a list of all link-layer header types provided by a device, call** **pcap\_list\_datalinks**() **on an activated** **pcap\_t** **for the device.** **To free a list of link-layer header types, call** **pcap\_free\_datalinks**(). **To set the link-layer header type for a device, call** **pcap\_set\_datalink**(). **This should be done after the device has been activated but before any** **packets are read and before any filters are compiled or installed.** - **Routines** - **pcap\_list\_datalinks**(3PCAP) **get a list of link-layer header types for a device** - **pcap\_free\_datalinks**(3PCAP) **free list of link-layer header types** - **pcap\_set\_datalink**(3PCAP) **set link-layer header type for a device** - **pcap\_datalink\_val\_to\_name**(3PCAP) **get name for a link-layer header type** - **pcap\_datalink\_val\_to\_description**(3PCAP) - **pcap\_datalink\_val\_to\_description\_or\_dlt**(3PCAP) **get description for a link-layer header type** - **pcap\_datalink\_name\_to\_val**(3PCAP) **get link-layer header type corresponding to a name** ### Reading packets **Packets are read with** **pcap\_dispatch**() **or** **pcap\_loop**(), **which process one or more packets, calling a callback routine for each** **packet, or with** **pcap\_next**() **or** **pcap\_next\_ex**(), **which return the next packet.** **The callback for** **pcap\_dispatch**() **and** **pcap\_loop**() **is supplied a pointer to a** **struct pcap\_pkthdr**, **which includes the following members:** - **ts** **a** **struct timeval** **containing the time when the packet was captured** - **caplen** **a** **bpf\_u\_int32** **giving the number of bytes of the packet that are available from the** **capture** - **len** **a** **bpf\_u\_int32** **giving the length of the packet, in bytes (which might be more than the** **number of bytes available from the capture, if the length of the packet** **was larger than the snapshot length or than some limit imposed by the** **capture mechanism).** **The callback is also supplied a** **const u\_char** **pointer to the first** **caplen** **(as given in the** **struct pcap\_pkthdr** **mentioned above)** **bytes of data from the packet. This won't necessarily be the entire** **packet; the default value used if** **pcap\_create**() **and** **pcap\_activate**() **are used to open a capture device, and no call to** **pcap\_set\_snaplen**() **is made before** **pcap\_activate**() **is called, should be sufficient for that device. However, if a smaller** **value is set with a call to** **pcap\_set\_snaplen**(), **if the default isn't sufficient for that device, or if the mechanism** **used by libpcap to capture the traffic imposes a separate limit,** **some captured packets may not contain all the data sent or received.** **When reading from a \`\`savefile'', the snapshot length specified when the** **capture was performed will limit the amount of packet data available.** **pcap\_next**() **is passed an argument that points to a** **struct pcap\_pkthdr** **structure, and fills it in with the time stamp and length values for the** **packet. It returns a** **const u\_char \*** **to the first** **caplen** **bytes of the packet on success, and** **a null pointer** **on error.** **pcap\_next\_ex**() **is passed two pointer arguments, one of which points to a** **struct pcap\_pkthdr \*** **and the other points to a** **const u\_char \***. **It sets the first pointer to point to a** **struct pcap\_pkthdr** **structure with the time stamp and length values for the packet, and sets** **the second pointer to point to the first** **caplen** **bytes of the packet.** **To force the loop in** **pcap\_dispatch**() **or** **pcap\_loop**() **to terminate, call** **pcap\_breakloop**(). **By default, when reading packets from an interface opened for a live** **capture,** **pcap\_dispatch**(), **pcap\_next**(), **and** **pcap\_next\_ex**() **will, if no packets are currently available to be read, block waiting** **for packets to become available. On some, but** *not* **all, platforms, if a packet buffer timeout was specified, the wait will** **terminate after the packet buffer timeout expires; applications should** **be prepared for this, as it happens on some platforms, but should not** **rely on it, as it does not happen on other platforms. Note that the** **wait might, or might not, terminate even if no packets are available;** **applications should be prepared for this to happen, but must not rely on** **it happening.** **A handle can be put into \`\`non-blocking mode'', so that those routines** **will, rather than blocking, return an indication that no packets are** **available to read. Call** **pcap\_setnonblock**() **to put a handle into non-blocking mode or to take it out of non-blocking** **mode; call** **pcap\_getnonblock**() **to determine whether a handle is in non-blocking mode. Note that** **non-blocking mode does not work correctly in Mac OS X 10.6.** **Non-blocking mode is often combined with routines such as** [**select**(2)](/select/2.md) **or** [**poll**(2)](/poll/2.md) **or other routines a platform offers to wait for any of a set of** **descriptors to be ready to read. To obtain, for a handle, a descriptor** **that can be used in those routines, call** **pcap\_get\_selectable\_fd**(). **If the routine indicates that data is** **available to read on the descriptor, an attempt should be made to read** **from the device.** **Not all handles have such a descriptor available;** **pcap\_get\_selectable\_fd**() **will return** **-1** **if no such descriptor is available. If no such** **descriptor is available, this may be because the device must be polled** **periodically for packets; in that case,** **pcap\_get\_required\_select\_timeout**() **will return a pointer to a** **struct timeval** **whose value can be used as a timeout in those routines. When the** **routine returns, an attempt should be made to read packets from the** **device. If** **pcap\_get\_required\_select\_timeout**() **returns** **a null timeout pointer for a device for which** **pcap\_get\_selectable\_fd**() **returned** **-1**, **no such timeout is available, and those routines cannot be** **used with the device.** **In addition, for various** **reasons, one or more of those routines will not work properly with the** **descriptor; the documentation for** **pcap\_get\_selectable\_fd**() **gives details. Note that, just as an attempt to read packets from a** **pcap\_t** **may not return any packets if the packet buffer timeout expires, a** **select**(), **poll**(), **or other such call may, if the packet buffer timeout expires, indicate** **that a descriptor is ready to read even if there are no packets** **available to read.** - **Routines** - **pcap\_dispatch**(3PCAP) **read a bufferful of packets from a** **pcap\_t** **open for a live capture or the full set of packets from a** **pcap\_t** **open for a \`\`savefile''** - **pcap\_loop**(3PCAP) **read packets from a** **pcap\_t** **until an interrupt or error occurs** - **pcap\_next**(3PCAP) **read the next packet from a** **pcap\_t** **without an indication whether an error occurred** - **pcap\_next\_ex**(3PCAP) **read the next packet from a** **pcap\_t** **with an error indication on an error** - **pcap\_breakloop**(3PCAP) **prematurely terminate the loop in** **pcap\_dispatch**() **or** **pcap\_loop**() - **pcap\_setnonblock**(3PCAP) **set or clear non-blocking mode on a** **pcap\_t** - **pcap\_getnonblock**(3PCAP) **get the state of non-blocking mode for a** **pcap\_t** - **pcap\_get\_selectable\_fd**(3PCAP) **attempt to get a descriptor for a** **pcap\_t** **that can be used in calls such as** **select**() **and** **poll**() - **pcap\_get\_required\_select\_timeout**(3PCAP) **attempt to get a timeout required for using a** **pcap\_t** **in calls such as** **select**() **and** **poll**() ### Filters **In order to cause only certain packets to be returned when reading** **packets, a filter can be set on a handle. For a live capture, the** **filtering will be performed in kernel mode, if possible, to avoid** **copying \`\`uninteresting'' packets from the kernel to user mode.** **A filter can be specified as a text string; the syntax and semantics of** **the string are as described by** [**pcap-filter**(7)](/pcap-filter/7.md). **A filter string is compiled into a program in a pseudo-machine-language** **by** **pcap\_compile**() **and the resulting program can be made a filter for a handle with** **pcap\_setfilter**(). **The result of** **pcap\_compile**() **can be freed with a call to** **pcap\_freecode**(). **pcap\_compile**() **may require a network mask for certain expressions in the filter string;** **pcap\_lookupnet**() **can be used to find the network address and network mask for a given** **capture device.** **A compiled filter can also be applied directly to a packet that has been** **read using** **pcap\_offline\_filter**(). - **Routines** - **pcap\_compile**(3PCAP) **compile filter expression to a pseudo-machine-language code program** - **pcap\_freecode**(3PCAP) **free a filter program** - **pcap\_setfilter**(3PCAP) **set filter for a** **pcap\_t** - **pcap\_lookupnet**(3PCAP) **get network address and network mask for a capture device** - **pcap\_offline\_filter**(3PCAP) **apply a filter program to a packet** ### Incoming and outgoing packets **By default, libpcap will attempt to capture both packets sent by the** **machine and packets received by the machine. To limit it to capturing** **only packets received by the machine or, if possible, only packets sent** **by the machine, call** **pcap\_setdirection**(). - **Routines** - **pcap\_setdirection**(3PCAP) **specify whether to capture incoming packets, outgoing packets, or both** ### Capture statistics **To get statistics about packets received and dropped in a live capture,** **call** **pcap\_stats**(). - **Routines** - **pcap\_stats**(3PCAP) **get capture statistics** ### Opening a handle for writing captured packets **To open a \`\`savefile\`\` to which to write packets, given the pathname the** **\`\`savefile'' should have, call** **pcap\_dump\_open**(); **to set up a handle for a \`\`savefile'', given a** **FILE \*** **referring to a file already opened for writing, call** **pcap\_dump\_fopen**(). **They each return pointers to a** **pcap\_dumper\_t**, **which is the handle used for writing packets to the \`\`savefile''. If it** **succeeds, it will have created the file if it doesn't exist and** **truncated the file if it does exist.** **To close a** **pcap\_dumper\_t**, **call** **pcap\_dump\_close**(). - **Routines** - **pcap\_dump\_open**(3PCAP) **open a** **pcap\_dumper\_t** **for a \`\`savefile\`\`, given a pathname, replacing any existing data** - **pcap\_dump\_open\_append**(3PCAP) **open a** **pcap\_dumper\_t** **for a \`\`savefile\`\`, given a pathname, appending to the existing data** - **pcap\_dump\_fopen**(3PCAP) **open a** **pcap\_dumper\_t** **for a \`\`savefile\`\`, given a** **FILE \***, **assuming an empty file** - **pcap\_dump\_close**(3PCAP) **close a** **pcap\_dumper\_t** - **pcap\_dump\_file**(3PCAP) **get the** **FILE \*** **for a** **pcap\_dumper\_t** **opened for a \`\`savefile''** ### Writing packets **To write a packet to a** **pcap\_dumper\_t**, **call** **pcap\_dump**(). **Packets written with** **pcap\_dump**() **may be buffered, rather than being immediately written to the** **\`\`savefile''. Closing the** **pcap\_dumper\_t** **will cause all buffered-but-not-yet-written packets to be written to the** **\`\`savefile''.** **To force all packets written to the** **pcap\_dumper\_t**, **and not yet written to the \`\`savefile'' because they're buffered by the** **pcap\_dumper\_t**, **to be written to the \`\`savefile'', without closing the** **pcap\_dumper\_t**, **call** **pcap\_dump\_flush**(). - **Routines** - **pcap\_dump**(3PCAP) **write packet to a** **pcap\_dumper\_t** - **pcap\_dump\_flush**(3PCAP) **flush buffered packets written to a** **pcap\_dumper\_t** **to the \`\`savefile''** - **pcap\_dump\_ftell**(3PCAP) **get current file position for a** **pcap\_dumper\_t** ### Injecting packets **If you have the required privileges, you can inject packets onto a** **network with a** **pcap\_t** **for a live capture, using** **pcap\_inject**() **or** **pcap\_sendpacket**(). **(The two routines exist for compatibility with both OpenBSD and** **WinPcap/Npcap; they perform the same function, but have different return** **values.)** - **Routines** - **pcap\_inject**(3PCAP) - **pcap\_sendpacket**(3PCAP) **transmit a packet** ### Reporting errors **Some routines return error or warning status codes; to convert them to a** **string, use** **pcap\_statustostr**(). - **Routines** - **pcap\_statustostr**(3PCAP) **get a string for an error or warning status code** ### Getting library version information **To get a string giving version information about libpcap, call** **pcap\_lib\_version**(). - **Routines** - **pcap\_lib\_version**(3PCAP) **get library version string** ## BACKWARD COMPATIBILITY **In versions of libpcap prior to 1.0, the** **pcap.h** **header file was not in a** **pcap** **directory on most platforms; if you are writing an application that must** **work on versions of libpcap prior to 1.0, include** **\**, **which will include** **\** **for you, rather than including** **\**. **pcap\_create**() **and** **pcap\_activate**() **were not available in versions of libpcap prior to 1.0; if you are** **writing an application that must work on versions of libpcap prior to** **1.0, either use** **pcap\_open\_live**() **to get a handle for a live capture or, if you want to be able to use the** **additional capabilities offered by using** **pcap\_create**() **and** **pcap\_activate**(), **use an** [**autoconf**(1)](/autoconf/1.md) **script or some other configuration script to check whether the libpcap** **1.0 APIs are available and use them only if they are.** ## SEE ALSO [**autoconf**(1)](/autoconf/1.md), [**tcpdump**(1)](/tcpdump/1.md), [**tcpslice**(1)](/tcpslice/1.md), [**pcap-filter**(7)](/pcap-filter/7.md), [**bpf**(4)](/bpf/4.md), [**usermod**(8)](/usermod/8.md) ## AUTHORS **The original authors of libpcap are:** **Van Jacobson,** **Craig Leres and** **Steven McCanne, all of the** **Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.** **The current version is available from "The Tcpdump Group"'s Web site at** *https://www.tcpdump.org/* ## BUGS **To report a security issue please send an e-mail to security@tcpdump.org.** **To report bugs and other problems, contribute patches, request a** **feature, provide generic feedback etc please see the file** *CONTRIBUTING.md* **in the libpcap source tree root.**